From 1cf134b495a712eb548b3d76dd85dbd7515138ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Claes=20Wallin=20=28=E9=9F=8B=E5=98=89=E8=AA=A0=29?= Date: Wed, 25 Apr 2018 14:08:58 +0800 Subject: [PATCH] Problem: asciidoc source interferes with styx templating Solution: Escape all single quote pairs as HTML entities. --- HOWTO.adoc | 26 +++++----- README.adoc | 6 +-- doc/quick-start.adoc | 26 +++++----- edges/README.adoc | 42 ++++++++-------- fractals/README.adoc | 2 +- nodes/README.adoc | 108 +++++++++++++++++++++--------------------- nodes/idr/README.adoc | 2 +- nodes/rs/README.adoc | 2 +- services/README.adoc | 4 +- 9 files changed, 109 insertions(+), 109 deletions(-) diff --git a/HOWTO.adoc b/HOWTO.adoc index 56fe621a..0240416c 100644 --- a/HOWTO.adoc +++ b/HOWTO.adoc @@ -223,13 +223,13 @@ image::https://raw.githubusercontent.com/fractalide/fractalide/master/doc/images image::https://raw.githubusercontent.com/fractalide/fractalide/master/doc/images/get.png[get] -[source, nix] +[source, nix, subs="none"] ---- { subgraph, nodes, edges }: subgraph { src = ./.; - flowscript = with nodes; with edges; '' + flowscript = with nodes; with edges; '' db_path => db_path get_sql() input => input id(${todo_get_id}) id -> get get_sql(${sqlite_local_get}) get_sql() id -> id todo_build_json(${todo_build_json}) @@ -238,7 +238,7 @@ subgraph { todo_build_json() json -> playload build_resp(${todo_build_response}) get_sql() error -> error build_resp() build_resp() response -> response todo_add_req_id() response => response - ''; + ''; } ---- @@ -271,13 +271,13 @@ Please understand how the code maps to the above diagram, as these particular di image::https://raw.githubusercontent.com/fractalide/fractalide/master/doc/images/post.png[post] -[source, nix] +[source, nix, subs="none"] ---- { subgraph, nodes, edges }: subgraph { src = ./.; - flowscript = with nodes; with edges; '' + flowscript = with nodes; with edges; '' db_path => db_path insert_todo() input => input todo_get_todo(${todo_get_todo}) todo -> input cl_todo(${msg_clone}) cl_todo() clone[0] -> insert insert_todo(${sqlite_local_insert}) @@ -286,7 +286,7 @@ subgraph { todo_get_todo() req_id -> id todo_add_req_id(${todo_add_req_id}) todo_build_json() json -> playload todo_build_response(${todo_build_response}) todo_build_response() response -> response todo_add_req_id() response => response - ''; + ''; } ---- @@ -316,20 +316,20 @@ post() response -> response http() image::https://raw.githubusercontent.com/fractalide/fractalide/master/doc/images/delete.png[delete] -[source, nix] +[source, nix, subs="none"] ---- { subgraph, nodes, edges }: subgraph { src = ./.; - flowscript = with nodes; with edges; '' + flowscript = with nodes; with edges; '' input => input id(${todo_get_id}) db_path => db_path delete_sql() id() id -> delete delete_sql(${sqlite_local_delete}) delete_sql() response -> playload build_resp(${todo_build_response}) id() req_id -> id todo_add_req_id(${todo_add_req_id}) build_resp() response -> response todo_add_req_id() response => response - ''; + ''; } ---- @@ -371,13 +371,13 @@ To simplify the graph a little, we've not mentioned the edge from `synch` to `pa image::https://raw.githubusercontent.com/fractalide/fractalide/master/doc/images/patch_final.png[patch_final] -[source, nix] +[source, nix, subs="none"] ---- { subgraph, nodes, edges }: subgraph { src = ./.; - flowscript = with nodes; with edges; '' + flowscript = with nodes; with edges; '' input => input todo_get_todo(${todo_get_todo}) db_path => db_path patch_sql() todo_get_todo() id -> get get_sql(${sqlite_local_get}) @@ -390,7 +390,7 @@ subgraph { get_sql() error -> error synch() error -> error build_resp() todo_get_todo() req_id -> id todo_add_req_id(${todo_add_req_id}) build_resp() response -> response todo_add_req_id() response => response - ''; + ''; } ---- @@ -426,7 +426,7 @@ You can also fiddle with Insert this into your `Configuration.nix` -[source, nix] +[source, nix, subs="none"] ---- { config, pkgs, ... }: diff --git a/README.adoc b/README.adoc index 9df082dc..889437a2 100644 --- a/README.adoc +++ b/README.adoc @@ -86,7 +86,7 @@ Flow-based programming in our books has delivered on its promise. In our system When nix is assigned the responsibility of declaratively building fbp `nodes`, a magic thing happens. All that manual overhead of having to build, manage and package etc gets done once and only once by the `node` author, and completely disappears for everyone thereafter. We're left with the reusable good parts that FBP has to offer. Indeed the greatest overhead a `node` user has, is typing the ``node``'s name. We've gone further and distilled the overhead to a few lines, no more intimidating than a typical config file such as `Cargo.toml`: -[source, nix] +[source, nix, subs="none"] ---- { agent, edges, mods, pkgs }: @@ -233,9 +233,9 @@ Now you can add and commit your changes: [source, sh] ---- $ git add changed_file.js //repeat for each file you changed -$ git commit -m 'problem: very short description of problem //do not close the '', press ENTER two (2) times +$ git commit -m 'problem: very short description of problem //do not close the '', press ENTER two (2) times > ->solution: short description of how you solved the problem.' //Now you can close the ''. Also mention the issue number if there is one (e.g. #6) +>solution: short description of how you solved the problem.' //Now you can close the ''. Also mention the issue number if there is one (e.g. #6) $ git push //this will send your changes to _your_ fork on Github ---- * Go to your fork on Github and select the branch you just worked on. Click "pull request" to send a pull request back to the Fractalide repository. diff --git a/doc/quick-start.adoc b/doc/quick-start.adoc index 7bcd9963..1aa1a1f1 100644 --- a/doc/quick-start.adoc +++ b/doc/quick-start.adoc @@ -16,7 +16,7 @@ $ cd fractalide The directory will have one file: -[source, nix] +[source, nix, subs="none"] .edges/prim/bool/default.nix ---- { edge, edges }: @@ -24,17 +24,17 @@ The directory will have one file: edge { src = ./.; edges = with edges; []; - schema = with edges; '' + schema = with edges; '' struct PrimBool { bool @0 :Bool; } - ''; + ''; } ---- * Now we need to make your new `edge` seen by the system. Insert your newly created `edge` into `edges/default.nix`. -[source, nix] +[source, nix, subs="none"] .edges/default.nix ---- { pkgs, support, ... }: @@ -185,7 +185,7 @@ $ touch nodes/rs/maths/boolean/nand/default.nix Then insert the below into the `default.nix` -[source, nix] +[source, nix, subs="none"] .nodes/rs/maths/boolean/nand/default.nix ---- { agent, edges, mods, pkgs }: @@ -205,7 +205,7 @@ Also `mods = with mods.rs; [ rustfbp capnp ];` is where we included our `crate` * We need to make our `NAND` seen by the system by adding it to `nodes/rs/default.nix` -[source, nix] +[source, nix, subs="none"] .nodes/rs/default.nix ---- { pkgs, support, ... }: @@ -241,18 +241,18 @@ touch nodes/rs/maths/boolean/not/default.nix Then insert the below into `default.nix`: -[source, nix] +[source, nix, subs="none"] .nodes/rs/maths/boolean/not/default.nix ---- { subgraph, nodes, edges }: subgraph { src = ./.; - flowscript = with nodes.rs; '' + flowscript = with nodes.rs; '' input => input clone(${msg_clone}) clone() clone[1] -> a nand(${maths_boolean_nand}) output => output clone() clone[2] -> b nand() - ''; + ''; } ---- @@ -262,7 +262,7 @@ Notice the `${maths_boolean_nand}` and `${msg_clone}`. Nix will replace these wi * Add your new NOT `subgraph` to the `nodes/rs/default.nix` -[source, nix] +[source, nix, subs="none"] .nodes/rs/default.nix ---- { pkgs, support, ... }: @@ -303,7 +303,7 @@ Notice the `${maths_boolean_nand}` and `${msg_clone}` were replaced with fully q First, edit `nodes/rs/test/not/default.nix` so that it looks like this: -[source, nix] +[source, nix, subs="none"] .nodes/rs/test/not/default.nix ---- { subgraph, imsg, nodes, edges }: @@ -317,9 +317,9 @@ let in subgraph { src = ./.; - flowscript = with nodes.rs; '' + flowscript = with nodes.rs; '' '${PrimBool}' -> input not(${maths_boolean_not}) output -> input io_print(${maths_boolean_print}) - ''; + ''; } ---- diff --git a/edges/README.adoc b/edges/README.adoc index 5211dffb..dfad3442 100644 --- a/edges/README.adoc +++ b/edges/README.adoc @@ -23,15 +23,15 @@ So despite you seeing only Cap'n Proto schema in this directory, the concept of When developing a `subgraph` there comes a time when the developer wants to inject data into an `agent` or another `subgraph`. One needs to use an `exposed edge` or an `imsg` (initial message) which has this syntax: -[source, nix] +[source, nix, subs="none"] ---- { subgraph, nodes, edges }: subgraph { src = ./.; - flowscript = with nodes; with edges; '' + flowscript = with nodes; with edges; '' '${prim_bool}:(boolean=true)' -> INPUT_PORT NAME() - ''; + ''; } ---- @@ -47,43 +47,43 @@ Examples of `hidden edges` * From one `agent` to another `agent`: -[source, nix] +[source, nix, subs="none"] ---- { subgraph, nodes, edges }: subgraph { src = ./.; - flowscript = with nodes; with edges; '' + flowscript = with nodes; with edges; '' agent1() output -> input agent2() - ''; + ''; } ---- * Into a `subgraph`: -[source, nix] +[source, nix, subs="none"] ---- { subgraph, nodes, edges }: subgraph { src = ./.; - flowscript = with nodes; with edges; '' + flowscript = with nodes; with edges; '' output => input subgraph() - ''; + ''; } ---- * Out of a `subgraph`: -[source, nix] +[source, nix, subs="none"] ---- { subgraph, nodes, edges }: subgraph { src = ./.; - flowscript = with nodes; with edges; '' + flowscript = with nodes; with edges; '' agent() output => output - ''; + ''; } ---- @@ -133,20 +133,20 @@ The `edge` building function accepts these arguments: * The `edges` attribute resolve transitive dependencies and ensures your `agent` has all the needed files to type check. * a https://capnproto.org[Cap 'n Proto] `schema`. This is the heart of the contract, this is where you may create potentially complex deep hierarchies of structured data. Please read more about the https://capnproto.org/language.html[schema language]. -[source, nix] +[source, nix, subs="none"] ---- { edge, edges }: edge { src = ./.; edges = with edges; [ command ]; - schema = with edges; '' + schema = with edges; '' @0xf61e7fcd2b18d862; using Command = import "${command}/src/edge.capnp"; struct ListCommand { commands @0 :List(Command.Command); } - ''; + ''; } ---- @@ -164,14 +164,14 @@ The same naming applies for Cap'n Proto `enums` and `interfaces`. It's crucial t We prefer composition of schema, and the schema must have fully qualified struct names. Hence, this is example shouldn't be used: -[source, nix] +[source, nix, subs="none"] ---- { edge, edges }: edge { src = ./.; edges = with edges; [ command ]; - schema = with edges; '' + schema = with edges; '' @0xf61e7fcd2b18d862; struct Person { name @0 :Text; @@ -197,7 +197,7 @@ edge { month @1 :UInt8; day @2 :UInt8; } - ''; + ''; } ---- @@ -211,20 +211,20 @@ Therefore to avoid this scenario please put `struct Date ...` into it's own sche Fractalide resolves transitive dependencies for you but you have to use this method: -[source, nix] +[source, nix, subs="none"] ---- { edge, edges }: edge { src = ./.; edges = with edges; [ command ]; - schema = with edges; '' + schema = with edges; '' @0xf61e7fcd2b18d862; using CommandInstanceName = import "${command}/src/edge.capnp"; struct ListCommand { commands @0 :List(CommandInstanceName.Command); } - ''; + ''; } ---- diff --git a/fractals/README.adoc b/fractals/README.adoc index 74d9a0a3..13468d11 100644 --- a/fractals/README.adoc +++ b/fractals/README.adoc @@ -58,7 +58,7 @@ Should you start a new shell, type `-r` then type `125ff` this will search Insert the below code into a file called `default.nix` which sits in the above folder. -[source, nix] +[source, nix, subs="none"] .dev/fractalide/fractals/net/http/default.nix ---- { pkgs diff --git a/nodes/README.adoc b/nodes/README.adoc index b8b5550a..e74527c9 100644 --- a/nodes/README.adoc +++ b/nodes/README.adoc @@ -51,24 +51,24 @@ The `Subgraph` `default.nix` requires you make decisions about two types of depe * What `Nodes` are needed? * What `Edges` are needed? -[source, nix] +[source, nix, subs="none"] .default.nix ---- { subgraph, imsg, nodes, edges }: let imsgTrue = imsg { class = edges.PrimBool; - text = ''(boolean=true)''; + text = ''(boolean=true)''; }; in subgraph { src = ./.; - flowscript = with nodes.rs;'' + flowscript = with nodes.rs;'' nand(${maths_boolean_nand}) '${imsgTrue}' -> a nand() '${imsgTrue}' -> b nand() nand() output -> input io_print(${maths_boolean_print}) - ''; + ''; } ---- @@ -77,7 +77,7 @@ image::https://raw.githubusercontent.com/fractalide/fractalide/master/doc/images * The `{ subgraph, nodes, edges }:` lambda passes in three arguments, the `subgraph` builder, `edges` which consists of every `Edge` or `Edge Namespace`, and the `nodes` argument which consists of every `Node` and `Node Namespace` in the system. * The `subgraph` building function accepts these arguments: ** The `src` attribute is used to derive a `Subgraph` name based on location in the directory hierarchy. -** The `flowscript` attribute defines the business logic. Here data flowing through a system becomes a first class citizen that can be manipulated. `Nodes` and `Edges` are brought into scope between the opening '' and closing '' double single quotes by using the `with nodes; with edges;` syntax. +** The `flowscript` attribute defines the business logic. Here data flowing through a system becomes a first class citizen that can be manipulated. `Nodes` and `Edges` are brought into scope between the opening '' and closing '' double single quotes by using the `with nodes; with edges;` syntax. * `Nix` assists us greatly, in that each `node` name (the stuff between the curly quotes ``${...}``) undergoes a compilation step resolving every name into an absolute `/path/to/compiled/lib.subgraph` text file and `/path/to/compiled/libagent.so` shared object. * This compilation is lazy and only referenced names will be compiled. In other words `Subgraph` could be a top level `Subgraph` of a many layer deep hierarchy and only referenced `Nodes` will be compiled in a lazy fashion, *not* the entire `fractalide/nodes` folder. @@ -96,17 +96,17 @@ Mother of the Flying Spaghetti Monster, what is that? One really doesn't need to === Flowscript syntax is easy -Everything between the opening `''` and closing `''` is `flowscript`, i.e: +Everything between the opening `''` and closing `''` is `flowscript`, i.e: -[source, nix] +[source, nix, subs="none"] ---- { subgraph, nodes, edges }: subgraph { src = ./.; - flowscript = with nodes.rs; '' + flowscript = with nodes.rs; '' <---- here - ''; + ''; } ---- @@ -115,15 +115,15 @@ image::https://raw.githubusercontent.com/fractalide/fractalide/master/doc/images ==== Agent initialization: -[source, nix] +[source, nix, subs="none"] ---- { subgraph, nodes, edges }: subgraph { src = ./.; - flowscript = with nodes.rs; '' + flowscript = with nodes.rs; '' agent_name(${name_of_agent}) - ''; + ''; } ---- @@ -131,16 +131,16 @@ image::https://raw.githubusercontent.com/fractalide/fractalide/master/doc/images ==== Referencing a previously initialized agent (with a comment): -[source, nix] +[source, nix, subs="none"] ---- { subgraph, nodes, edges }: subgraph { src = ./.; - flowscript = with nodes.rs; '' + flowscript = with nodes.rs; '' agent_name(${name_of_agent}) // <──┐ agent_name() // <──┴─ same instance - ''; + ''; } ---- @@ -148,15 +148,15 @@ image::https://raw.githubusercontent.com/fractalide/fractalide/master/doc/images ==== Connecting and initializing two agents: -[source, nix] +[source, nix, subs="none"] ---- { subgraph, nodes, edges }: subgraph { src = ./.; - flowscript = with nodes.rs; '' + flowscript = with nodes.rs; '' agent1(${name_of_agent1}) output_port -> input_port agent2(${name_of_agent2}) - ''; + ''; } ---- @@ -166,20 +166,20 @@ If the connection between `output_port` and `input_port` have the same `schema`, ==== Creating an <> -[source, nix] +[source, nix, subs="none"] ---- { subgraph, imsg, nodes, edges }: let imsgTrue = imsg { class = edges.PrimBool; - text = ''(boolean=true)''; + text = ''(boolean=true)''; }; in subgraph { src = ./.; - flowscript = with nodes.rs; '' + flowscript = with nodes.rs; '' '${imsgTrue}' -> a agent(${name_of_agent}) - ''; + ''; } ---- @@ -187,22 +187,22 @@ image::https://raw.githubusercontent.com/fractalide/fractalide/master/doc/images ==== More complex iMsg or Exposed Edge -[source, nix] +[source, nix, subs="none"] ---- { subgraph, imsg, edges, nodes }: let UiJsCreate = imsg { class = edges.UiJsCreate; - text = ''(type="div", style=(list=[(key=(text="display"), val=(text="flex")), (key=(text="flex-direction"), val=(text="column"))]))''; + text = ''(type="div", style=(list=[(key=(text="display"), val=(text="flex")), (key=(text="flex-direction"), val=(text="column"))]))''; option = "create"; }; in subgraph { src = ./.; - flowscript = with nodes.rs; '' + flowscript = with nodes.rs; '' td(${ui_js_nodes.flex}) '${UiJsCreate}' -> input td() - ''; + ''; } ---- @@ -213,15 +213,15 @@ image::https://raw.githubusercontent.com/fractalide/fractalide/master/doc/images ==== Creating an subgraph input port -[source, nix] +[source, nix, subs="none"] ---- { subgraph, nodes, edges }: subgraph { src = ./.; - flowscript = with nodes.rs; '' + flowscript = with nodes.rs; '' subgraph_input => input agent(${name_of_agent}) - ''; + ''; } ---- @@ -229,15 +229,15 @@ image::https://raw.githubusercontent.com/fractalide/fractalide/master/doc/images ==== Creating an subgraph output port -[source, nix] +[source, nix, subs="none"] ---- { subgraph, nodes, edges }: subgraph { src = ./.; - flowscript = with nodes.rs; '' + flowscript = with nodes.rs; '' agent(${name_of_agent}) output => subgraph_output - ''; + ''; } ---- @@ -245,15 +245,15 @@ image::https://raw.githubusercontent.com/fractalide/fractalide/master/doc/images ==== Subgraph initialization: -[source, nix] +[source, nix, subs="none"] ---- { subgraph, nodes, edges }: subgraph { src = ./.; - flowscript = with nodes.rs; '' + flowscript = with nodes.rs; '' subgraph(${name_of_subgraph}) - ''; + ''; } ---- @@ -261,17 +261,17 @@ image::https://raw.githubusercontent.com/fractalide/fractalide/master/doc/images ==== Initializing a subgraph and agent then connecting them: -[source, nix] +[source, nix, subs="none"] ---- { subgraph, nodes, edges }: subgraph { src = ./.; - flowscript = with nodes.rs; '' + flowscript = with nodes.rs; '' subgraph(${name_of_subgraph}) agent(${name_of_agent}) subgraph() output -> input agent() - ''; + ''; } ---- @@ -279,19 +279,19 @@ image::https://raw.githubusercontent.com/fractalide/fractalide/master/doc/images ==== Output array port: -[source, nix] +[source, nix, subs="none"] ---- { subgraph, nodes, edges }: subgraph { src = ./.; - flowscript = with nodes.rs; '' + flowscript = with nodes.rs; '' db_path => input clone(${msg_clone}) clone() clone[0] => db_path0 clone() clone[1] => db_path1 clone() clone[2] => db_path2 clone() clone[3] => db_path3 - ''; + ''; } ---- @@ -301,18 +301,18 @@ NOTE: `clone[1]` is an `array output port` and in this particular `Subgraph` `Me ==== Input array port: -[source, nix] +[source, nix, subs="none"] ---- { subgraph, nodes, edges }: subgraph { src = ./.; - flowscript = with nodes.rs; '' + flowscript = with nodes.rs; '' add0 => add[0] adder(${path_to_adder}) add1 => add[1] adder() add2 => add[2] adder() add3 => add[3] adder() output -> output - ''; + ''; } ---- @@ -322,17 +322,17 @@ image::https://raw.githubusercontent.com/fractalide/fractalide/master/doc/images ==== Hierarchical naming: -[source, nix] +[source, nix, subs="none"] ---- { subgraph, nodes, edges }: subgraph { src = ./.; - flowscript = with nodes.rs; '' + flowscript = with nodes.rs; '' input => input clone(${msg_clone}) clone() clone[0] -> a nand(${maths_boolean_nand}) clone() clone[1] -> b nand() output => output - ''; + ''; } ---- @@ -348,23 +348,23 @@ The above implements the `not` boolean logic operation. ==== Abstraction powers: -[source, nix] +[source, nix, subs="none"] ---- { subgraph, nodes, edges }: let imsgTrue = imsg { class = edges.PrimBool; - text = ''(boolean=true)''; + text = ''(boolean=true)''; }; in subgraph { src = ./.; - flowscript = with nodes.rs; '' + flowscript = with nodes.rs; '' '${imsgTrue}' -> a nand(${maths_boolean_nand}) '${imsgTrue}' -> b nand() nand() output -> input not(${maths_boolean_not}) not() output -> input print(${maths_boolean_print}) - ''; + ''; } ---- @@ -374,13 +374,13 @@ Notice we're using the `not` node implemented earlier. One can build hierarchies ==== Namespaces -[source, nix] +[source, nix, subs="none"] ---- { subgraph, nodes, edges }: subgraph { src = ./.; - flowscript = with nodes; with edges; '' + flowscript = with nodes; with edges; '' listen => listen http(${net_http_nodes.http}) db_path => input clone(${msg_clone}) clone() clone[1] -> db_path get(${app_todo_nodes.todo_get}) @@ -393,7 +393,7 @@ subgraph { http() DELETE[/todos/.+] -> input del() response -> response http() http() PATCH[/todos/.+] -> input patch() http() PUT[/todos/.+] -> input patch() response -> response http() - ''; + ''; } ---- diff --git a/nodes/idr/README.adoc b/nodes/idr/README.adoc index 15fd935d..ef267aa7 100644 --- a/nodes/idr/README.adoc +++ b/nodes/idr/README.adoc @@ -61,7 +61,7 @@ The `agent` function in the `default.nix` requires you make decisions about thre * What `mods` which are idris library dependencies available online. * What `osdeps` or `operating system level dependencies` are needed? -[source, nix] +[source, nix, subs="none"] ---- { agent, edges, mods, pkgs }: diff --git a/nodes/rs/README.adoc b/nodes/rs/README.adoc index 8d5d1ec2..3722bf85 100644 --- a/nodes/rs/README.adoc +++ b/nodes/rs/README.adoc @@ -67,7 +67,7 @@ The `agent` function in the `default.nix` requires you make decisions about thre * What `mods` from https://crates.io[crates.io] are needed? * What `osdeps` or `operating system level dependencies` are needed? -[source, nix] +[source, nix, subs="none"] ---- { agent, edges, mods, pkgs }: diff --git a/services/README.adoc b/services/README.adoc index 611a1d29..051d46b1 100644 --- a/services/README.adoc +++ b/services/README.adoc @@ -35,7 +35,7 @@ This approach is when you have a service you don't consider generic and is not w in your `configuration.nix` put these lines: -[source, nix] +[source, nix, subs="none"] .configuration.nix ---- { config, pkgs, ... }: @@ -67,7 +67,7 @@ in in your `configuration.nix` put these lines: -[source, nix] +[source, nix, subs="none"] .configuration.nix ---- let