oolshjd

src/SUMMARY.md

@@ -63,7 +63,11 @@ Robust Toolbox
   - [Entity Coordinates](en/robust-toolbox/transform/entity-coordinates.md)
   - [Physics](en/robust-toolbox/transform/physics.md)
   - [Grids](en/robust-toolbox/transform/grids.md)
-- [Toolshed Shell](en/robust-toolbox/toolshed-shell.md)
+- [Toolshed](en/robust-toolbox/toolshed.md)
+  - [Types](en/robust-toolbox/toolshed/types.md)
+  - [Toolshed and (S)CSI](en/robust-toolbox/toolshed/toolshed-and-scsi.md)
+  - [Commands](en/robust-toolbox/toolshed/commands.md)
+    - [Entities](en/robust-toolbox/toolshed/commands/entity-control.md)
 - [User Interface](en/robust-toolbox/user-interface.md)
 - [IoC](en/robust-toolbox/ioc.md)
 - [Rendering]()

src/en/robust-toolbox/toolshed.md

@@ -0,0 +1,34 @@
+# Toolshed
+
+{{#template ../templates/wip.md}}
+
+Toolshed is one of the three primary built-in debug tools (alongside `scsi` and View Variables.) for RobustToolbox, functioning as the game's development console. To use Toolshed, open the debug console or use the debug console in `devwindow`.
+
+```admonish warning
+Toolshed is not yet available on the client, so you need to use the `>` prefix command on the client in order to run its commands server-side.
+```
+
+Toolshed is a **pipeline shell**, and the primary method of performing complex actions is composition of commands. You can simply write multiple commands one after the other and as long as they are compatible, they will have their inputs successively fed to one another. For example, take the following **command run**:
+
+```
+entities with Item count
+```
+
+This is three commands, `entities`, `with`, and `count`. They together form a **command run**, a set of successive commands. You can use the `explain` command to provide information about a command run's flow. It's highly recommended you `explain` command runs you don't understand to get an idea of their flow.
+
+```
+{{#include toolshed/explain_example_1.txt}}
+```
+a
+As the `explain` output might suggest, Toolshed is a strongly typed language. All commands have a type signature, and this signature can vary dynamically based on the type of the piped in value and on any **type arguments** provided.
+
+For example, the `comp` command has the signature `IEnumerable<EntityUid> -> IEnumerable<T>`, where T is any user specified component.
+
+```
+{{#include toolshed/explain_example_2.txt}}
+```
+
+Toolshed also supports variables in which you can store values. You can use the `=>` command to do this. Variables can then be used anywhere a command accepts a `ValueRef`, which can be a block, constant, or variable. You can put `=>` in the middle of a command run as well to tee the value.
+```
+{{#include toolshed/explain_example_3.txt}}
+```

src/en/robust-toolbox/toolshed/commands.md

@@ -0,0 +1,32 @@
+# Commands
+This is not the list of commands, that'd be this page's subpages.
+## Notation
+There's some notation within the command pages worth knowing.
+### Section titles.
+The following are the most common section titles and their purposes:
+<table>
+<thead>
+  <tr>
+    <th>Name</th>
+    <th>Description</th>
+  </tr>
+</thead>
+<tbody>
+  <tr>
+    <td>Sources</td>
+    <td>Commands that produce a list of some interesting value, that can then be filtered down and operated on.</td>
+  </tr>
+  <tr>
+    <td>Filters</td>
+    <td>Commands that filter down the input, i.e. removing unwanted values.</td>
+  </tr>
+  <tr>
+    <td>Transformers</td>
+    <td>Commands that transform the input to another type.</td>
+  </tr>
+  <tr>
+    <td>Mutators</td>
+    <td>Commands that mutate the input in some way.</td>
+  </tr>
+</tbody>
+</table>

src/en/robust-toolbox/toolshed/commands/entity-control.md

@@ -0,0 +1,78 @@
+# Entity commands
+{{#title Entity commands}}
+## Sources
+{{#template 
+    ../../../templates/toolshed-command-head.md
+    name=entities
+    typesig=[none] -> IEnumerable<EntityUid>
+}}
+Returns a list of all entities in the simulation.
+
+{{#template 
+    ../../../templates/toolshed-command-head.md
+    name=ent &lt;entity&gt;
+    typesig=[none] -> EntityUid
+}}
+Returns the given entity.
+
+## Filters
+{{#template 
+    ../../../templates/toolshed-command-head.md
+    name=with &lt;component type&gt;
+    typesig=IEnumerable<EntityUid> -> IEnumerable<EntityUid>
+}}
+Filters the input for entities with some given component.
+This command can be inverted with `not`.
+
+{{#template 
+    ../../../templates/toolshed-command-head.md
+    name=prototyped &lt;prototype&gt;
+    typesig=IEnumerable<EntityUid> -> IEnumerable<EntityUid>
+}}
+Filters the input for entities built from a given prototype.
+This command can be inverted with `not`.
+
+{{#template 
+    ../../../templates/toolshed-command-head.md
+    name=paused
+    typesig=IEnumerable<EntityUid> -> IEnumerable<EntityUid>
+}}
+Filters the input for entities that are currently paused.
+This command can be inverted with `not`.
+
+{{#template 
+    ../../../templates/toolshed-command-head.md
+    name=named &lt;name&gt;
+    typesig=IEnumerable<EntityUid> -> IEnumerable<EntityUid>
+}}
+Filters the input for entities with a name matching the regex `$regex^`.
+
+## Transforms
+{{#template 
+    ../../../templates/toolshed-command-head.md
+    name=comp:has &lt;component type&gt;
+    typesig=IEnumerable?<EntityUid> -> IEnumerable?<bool>
+}}
+Returns true if the input entity has the given component, otherwise false.
+
+{{#template 
+    ../../../templates/toolshed-command-head.md
+    name=pos
+    typesig=IEnumerable?<EntityUid> -> IEnumerable?<EntityCoordinates>
+}}
+Returns the coordinates of the input entities, relative to their parent.
+
+{{#template 
+    ../../../templates/toolshed-command-head.md
+    name=mappos
+    typesig=IEnumerable?<EntityUid> -> IEnumerable?<EntityCoordinates>
+}}
+Returns the coordinates of the input entities, relative to the map.
+
+## Mutators
+{{#template 
+    ../../../templates/toolshed-command-head.md
+    name=delete
+    typesig=IEnumerable<EntityUid> -> [none]
+}}
+Deletes the inputs from the simulation. Gone. Poof.

src/en/robust-toolbox/toolshed/explain_example_1.txt

@@ -0,0 +1,10 @@
+> explain entities with Item count
+entities: Returns all entities on the server.
+[none] -> IEnumerable<EntityUid>
+
+with: Filters the input entities by whether or not they have the given component.
+This command can be inverted with not.
+IEnumerable<EntityUid> -> IEnumerable<EntityUid>
+
+count: Counts the amount of entries in it's input, returning an integer.
+IEnumerable<EntityUid> -> Int32

src/en/robust-toolbox/toolshed/explain_example_2.txt

@@ -0,0 +1,6 @@
+> explain entities comp Item
+entities: Returns all entities on the server.
+[none] -> IEnumerable<EntityUid>
+
+comp: Returns the given component from the input entities, discarding entities without that component.
+IEnumerable<EntityUid> -> IEnumerable<ItemComponent>

src/en/robust-toolbox/toolshed/explain_example_3.txt

@@ -0,0 +1,25 @@
+> entities count => $myCount
+1783
+
+> explain entities count => $myCount
+entities: Returns all entities on the server.
+[none] -> IEnumerable<EntityUid>
+
+count: Counts the amount of entries in it's input, returning an integer.
+IEnumerable<EntityUid> -> Int32
+
+=>: Assigns the input to a variable.
+Int32 -> Int32
+
+> entities => $ents count
+1783
+
+> val IEnumerable<EntityUid> $ents
+ (1, Sandbox),
+Dev (1052, StandardNanotrasenStation),
+Dev (3),
+ (4),
+advanced capacitor (5, AdvancedCapacitorStockPart),
+air alarm (6, AirAlarm),
+Air canister (7, AirCanister),
+...

src/en/robust-toolbox/toolshed/toolshed-and-scsi.md

@@ -0,0 +1,13 @@
+# Toolshed and (S)CSI
+Toolshed can be invoked freely from scsi with the `object? tsh(string toolshedCommand)`, `T tsh<T>(string toolshedCommand)`, and `TOut tsh<TIn, TOut>(TIn value, string toolshedCommand)` functions. You can additionally call any of the IInvocationContext functions like ReadVar, WriteVar, and co in the interactive context, as the context implements IInvocationContext.
+```admonish warning
+`csi` and `scsi` Toolshed variables are not shared with the development console, they are different contexts.
+Toolshed in C# scripting can invoke all commands regardless of permissions, ala the server console.
+You may need to manually initialize Toolshed on the client by calling `ToolshedManager.Initialize()` if using csi.
+```
+
+## Toolshed call semantics
+Toolshed commands automatically have the providied initial value "piped in", meaning the first command provided must fit the initial value. If no initial value is provided, this type is `[none]`, which matches normal development console semantics. If a value is provided, Toolshed will expect the first command to fit the signature `TIn -> ???` where TIn is the type of or some downcast of the provided value.
+
+## Toolshed expression type vs the real type
+As you may have guessed, the return value of a toolshed command invocation is not necessarily the actual type of the value returned, often being an interface or other higher level type which is not itself constructable. **There are no guarantees for what the underlying type is and you shouldn't make assumptions about it.**

src/en/robust-toolbox/toolshed/types.md

@@ -0,0 +1,21 @@
+# Types
+Toolshed's type system is, **for the most part** that of C#'s. Toolshed adds some additional type rules for the convenience of both users and developers.
+
+## For users
+### All values are a list of length 1 (`T -> IEnumerable<T>`)
+Toolshed will automatically cast a lone value into a list containing only that value, if necessary. This lets you apply enumerable only commands to single values if necessary.
+
+### Any collection of T is an `IEnumerable<T>`
+This isn't technically toolshed specific, but it's useful to know that one can use a `List<T>`, `HashSet<T>`, `Dictionary<K,V>`, etc, as the input to any command taking an enumerable.
+
+### `IEnumerable<T>` is boxed into `List<T>` on assignment.
+When assigning an enumerable to a variable, Toolshed will automatically coerce it into a list to fully evaluate it and allow you to reuse it.
+Within C#, using an `IEnumerable<T>` more than once is disallowed, hence this coersion. 
+
+## For developers
+### Co-variance and Contra-variance limitations.
+Toolshed will refuse to do complex assignability checks for types with more than one co-variant or contra-variant argument, as to avoid combinatorial explosion from searching all possible types to use.
+
+### `IAsType<T>` and implicit casting.
+Toolshed will, for any type implementing `IAsType<T>`, consider T to be a valid implicit cast for that type.
+For example, if `Foo : IAsType<Bar>`, Toolshed will use the IAsType implementation to obtain Bar from Foo if it'd allow it to successfully typecheck a command run.

src/en/templates/toolshed-command-head.md

@@ -0,0 +1,9 @@
+<div style="display: flex; justify-content: space-between; align-items: center;">
+<div>
+<h3>[[#name]]</h3>
+</div>
+<div style="text-align: right;">
+
+`[[#typesig]]`
+</div>
+</div>

theme/ss14.css

@@ -60,4 +60,8 @@ main h1,
 main h2,
 main h3 {
     clear: both;
+}
+
+.navy code {
+    background: #0f0f12 !important;
 }