From c439a3d47794bac2934a569bb020f32e20aaafb0 Mon Sep 17 00:00:00 2001 From: Justin Starry Date: Sat, 23 Nov 2019 16:50:20 -0500 Subject: [PATCH] Clean up comments, generics names, and variable names (#752) --- README.md | 9 +-- src/agent.rs | 4 +- src/html/mod.rs | 2 +- src/html/scope.rs | 15 ++-- src/virtual_dom/mod.rs | 4 +- src/virtual_dom/vcomp.rs | 146 +++++++++++++++++++-------------------- src/virtual_dom/vlist.rs | 15 ++-- src/virtual_dom/vnode.rs | 18 +++-- src/virtual_dom/vtag.rs | 6 +- 9 files changed, 113 insertions(+), 106 deletions(-) diff --git a/README.md b/README.md index b2fac7272..80f1d1220 100644 --- a/README.md +++ b/README.md @@ -157,7 +157,7 @@ impl Agent for Worker { type Input = Request; type Output = Response; - // Create an instance with a link to agent's environment. + // Create an instance with a link to the agent. fn create(link: AgentLink) -> Self { Worker { link } } @@ -271,12 +271,9 @@ html! { } ``` -### Virtual DOM, independent loops, fine updates +### Virtual DOM -Yew uses its own **virtual-dom** implementation. It updates the browser's DOM -with tiny patches when properties of elements have changed. Every component lives -in its own independent loop interacting with the environment (`Scope`) through message passing -and supports a fine control of rendering. +Yew uses its own **virtual-dom** implementation. It updates the browser's DOM with tiny patches when properties of elements have changed. Every component can be interacted with using its (`Scope`) to pass messages and trigger updates. The `ShouldRender` returns the value which informs the loop when the component should be re-rendered: diff --git a/src/agent.rs b/src/agent.rs index a5db4ed84..92a1975a1 100644 --- a/src/agent.rs +++ b/src/agent.rs @@ -859,8 +859,8 @@ where return; } match self.update { - AgentUpdate::Create(env) => { - this.agent = Some(AGN::create(env)); + AgentUpdate::Create(link) => { + this.agent = Some(AGN::create(link)); } AgentUpdate::Message(msg) => { this.agent diff --git a/src/html/mod.rs b/src/html/mod.rs index bf7efc956..968957d15 100644 --- a/src/html/mod.rs +++ b/src/html/mod.rs @@ -330,7 +330,7 @@ impl NodeRef { } } -/// Should be rendered relative to context and component environment. +/// Trait for rendering virtual DOM elements pub trait Renderable { /// Called by rendering loop. fn render(&self) -> Html; diff --git a/src/html/scope.rs b/src/html/scope.rs index 4ed6996cf..75a6d12d5 100644 --- a/src/html/scope.rs +++ b/src/html/scope.rs @@ -6,7 +6,7 @@ use std::fmt; use std::rc::Rc; use stdweb::web::Element; -/// Updates for a `Components` instance. Used by scope sender. +/// Updates for a `Component` instance. Used by scope sender. pub(crate) enum ComponentUpdate { /// Wraps messages for a component. Message(COMP::Message), @@ -16,8 +16,7 @@ pub(crate) enum ComponentUpdate { Properties(COMP::Properties), } -/// A context which contains a bridge to send a messages to a loop. -/// Mostly services uses it. +/// A context which allows sending messages to a component. pub struct Scope { shared_state: Shared>, } @@ -60,7 +59,7 @@ impl Scope { let mut scope = self.clone(); let link = ComponentLink::connect(&scope); let ready_state = ReadyState { - env: self.clone(), + scope: self.clone(), element, node_ref, link, @@ -136,7 +135,7 @@ impl fmt::Display for ComponentState { } struct ReadyState { - env: Scope, + scope: Scope, element: Element, node_ref: NodeRef, props: COMP::Properties, @@ -148,7 +147,7 @@ impl ReadyState { fn create(self) -> CreatedState { CreatedState { component: COMP::create(self.props, self.link), - env: self.env, + scope: self.scope, element: self.element, last_frame: self.ancestor, node_ref: self.node_ref, @@ -157,7 +156,7 @@ impl ReadyState { } struct CreatedState { - env: Scope, + scope: Scope, element: Element, component: COMP, last_frame: Option>, @@ -176,7 +175,7 @@ impl CreatedState { fn update(mut self) -> Self { let mut next_frame = self.component.render(); - let node = next_frame.apply(&self.element, None, self.last_frame, &self.env); + let node = next_frame.apply(&self.element, None, self.last_frame, &self.scope); self.node_ref.set(node); self.last_frame = Some(next_frame); self diff --git a/src/virtual_dom/mod.rs b/src/virtual_dom/mod.rs index 6f11ecb2d..5d5582134 100644 --- a/src/virtual_dom/mod.rs +++ b/src/virtual_dom/mod.rs @@ -162,7 +162,7 @@ pub trait VDiff { /// find where to put the node. /// - `ancestor`: the node that this node will be replacing in the DOM. /// This method will _always_ remove the `ancestor` from the `parent`. - /// - `env`: the `Env`. + /// - `parent_scope`: the parent `Scope` used for passing messages to the parent `Component`. /// /// ### Internal Behavior Notice: /// @@ -177,6 +177,6 @@ pub trait VDiff { parent: &Element, previous_sibling: Option<&Node>, ancestor: Option>, - scope: &Scope, + parent_scope: &Scope, ) -> Option; } diff --git a/src/virtual_dom/vcomp.rs b/src/virtual_dom/vcomp.rs index ed1a6276b..754eb0de6 100644 --- a/src/virtual_dom/vcomp.rs +++ b/src/virtual_dom/vcomp.rs @@ -14,8 +14,8 @@ struct Hidden; type HiddenScope = *mut Hidden; -/// The method generates an instance of a (child) component. -type Generator = dyn FnOnce(GeneratorType, Scope) -> Mounted; +/// The method generates an instance of a component. +type Generator = dyn FnOnce(GeneratorType, Scope) -> Mounted; /// Components can be generated by mounting or by overwriting an old component. enum GeneratorType { @@ -23,19 +23,13 @@ enum GeneratorType { Overwrite(TypeId, HiddenScope), } -/// A reference to unknown scope which will be attached later with a generator function. -pub type ScopeHolder = Rc>>>; +/// A reference to the parent's scope which will be used later to send messages. +pub type ScopeHolder = Rc>>>; /// A virtual component. -pub struct VComp { +pub struct VComp { type_id: TypeId, - state: Rc>>, -} - -impl fmt::Debug for VComp { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str("VComp<_>") - } + state: Rc>>, } /// A virtual child component. @@ -48,12 +42,6 @@ pub struct VChild { node_ref: NodeRef, } -impl fmt::Debug for VChild { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str("VChild<_,_>") - } -} - impl VChild where SELF: Component, @@ -69,26 +57,26 @@ where } } -impl From> for VComp +impl From> for VComp where - COMP: Component, - CHILD: Component, + SELF: Component, + PARENT: Component, { - fn from(vchild: VChild) -> Self { - VComp::new::(vchild.props, vchild.scope, vchild.node_ref) + fn from(vchild: VChild) -> Self { + VComp::new::(vchild.props, vchild.scope, vchild.node_ref) } } -enum MountState { - Unmounted(Unmounted), +enum MountState { + Unmounted(Unmounted), Mounted(Mounted), Mounting, Detached, Overwritten, } -struct Unmounted { - generator: Box>, +struct Unmounted { + generator: Box>, } struct Mounted { @@ -97,21 +85,21 @@ struct Mounted { destroyer: Box, } -impl VComp { +impl VComp { /// This method prepares a generator to make a new instance of the `Component`. - pub fn new( - props: CHILD::Properties, - scope_holder: ScopeHolder, + pub fn new( + props: SELF::Properties, + scope_holder: ScopeHolder, node_ref: NodeRef, ) -> Self where - CHILD: Component, + SELF: Component, { - let generator = move |generator_type: GeneratorType, parent: Scope| -> Mounted { + let generator = move |generator_type: GeneratorType, parent: Scope| -> Mounted { *scope_holder.borrow_mut() = Some(parent); match generator_type { GeneratorType::Mount(element, ancestor) => { - let scope: Scope = Scope::new(); + let scope: Scope = Scope::new(); // TODO Consider to send ComponentUpdate::Create after `mount_in_place` call let mut scope = scope.mount_in_place( @@ -128,12 +116,12 @@ impl VComp { } } GeneratorType::Overwrite(type_id, scope) => { - if type_id != TypeId::of::() { + if type_id != TypeId::of::() { panic!("tried to overwrite a different type of component"); } let mut scope = unsafe { - let raw: *mut Scope = scope as *mut Scope; + let raw: *mut Scope = scope as *mut Scope; *Box::from_raw(raw) }; @@ -149,7 +137,7 @@ impl VComp { }; VComp { - type_id: TypeId::of::(), + type_id: TypeId::of::(), state: Rc::new(RefCell::new(MountState::Unmounted(Unmounted { generator: Box::new(generator), }))), @@ -157,83 +145,83 @@ impl VComp { } } -/// Converts property and attach empty scope holder which will be activated later. -pub trait Transformer { +/// Transforms properties and attaches a parent scope holder to callbacks for sending messages. +pub trait Transformer { /// Transforms one type to another. - fn transform(scope_holder: ScopeHolder, from: FROM) -> TO; + fn transform(scope_holder: ScopeHolder, from: FROM) -> TO; } -impl Transformer for VComp +impl Transformer for VComp where - COMP: Component, + PARENT: Component, { - fn transform(_: ScopeHolder, from: T) -> T { + fn transform(_: ScopeHolder, from: T) -> T { from } } -impl<'a, COMP, T> Transformer for VComp +impl<'a, PARENT, T> Transformer for VComp where - COMP: Component, + PARENT: Component, T: Clone, { - fn transform(_: ScopeHolder, from: &'a T) -> T { + fn transform(_: ScopeHolder, from: &'a T) -> T { from.clone() } } -impl<'a, COMP> Transformer for VComp +impl<'a, PARENT> Transformer for VComp where - COMP: Component, + PARENT: Component, { - fn transform(_: ScopeHolder, from: &'a str) -> String { + fn transform(_: ScopeHolder, from: &'a str) -> String { from.to_owned() } } -impl<'a, COMP, F, IN> Transformer> for VComp +impl<'a, PARENT, F, IN> Transformer> for VComp where - COMP: Component, - F: Fn(IN) -> COMP::Message + 'static, + PARENT: Component, + F: Fn(IN) -> PARENT::Message + 'static, { - fn transform(scope: ScopeHolder, from: F) -> Callback { + fn transform(scope: ScopeHolder, from: F) -> Callback { let callback = move |arg| { let msg = from(arg); if let Some(ref mut sender) = *scope.borrow_mut() { sender.send_message(msg); } else { - panic!("unactivated callback, parent component have to activate it"); + panic!("Parent component hasn't activated this callback yet"); } }; callback.into() } } -impl<'a, COMP, F, IN> Transformer>> for VComp +impl<'a, PARENT, F, IN> Transformer>> for VComp where - COMP: Component, - F: Fn(IN) -> COMP::Message + 'static, + PARENT: Component, + F: Fn(IN) -> PARENT::Message + 'static, { - fn transform(scope: ScopeHolder, from: F) -> Option> { + fn transform(scope: ScopeHolder, from: F) -> Option> { let callback = move |arg| { let msg = from(arg); if let Some(ref mut sender) = *scope.borrow_mut() { sender.send_message(msg); } else { - panic!("unactivated callback, parent component have to activate it"); + panic!("Parent component hasn't activated this callback yet"); } }; Some(callback.into()) } } -impl Unmounted { - /// mount a virtual component with a generator. +impl Unmounted { + /// Mount a virtual component using a generator. fn mount( self, parent: &T, ancestor: Node, // Any dummy expected - env: Scope, + parent_scope: Scope, ) -> Mounted { let element: Element = parent .as_node() @@ -241,12 +229,12 @@ impl Unmounted { .to_owned() .try_into() .expect("element expected to mount VComp"); - (self.generator)(GeneratorType::Mount(element, ancestor), env) + (self.generator)(GeneratorType::Mount(element, ancestor), parent_scope) } - /// Overwrite an existing virtual component with a generator. - fn replace(self, type_id: TypeId, old: Mounted, env: Scope) -> Mounted { - (self.generator)(GeneratorType::Overwrite(type_id, old.scope), env) + /// Overwrite an existing virtual component using a generator. + fn replace(self, type_id: TypeId, old: Mounted, parent_scope: Scope) -> Mounted { + (self.generator)(GeneratorType::Overwrite(type_id, old.scope), parent_scope) } } @@ -285,7 +273,7 @@ where parent: &Element, previous_sibling: Option<&Node>, ancestor: Option>, - env: &Scope, + parent_scope: &Scope, ) -> Option { match self.state.replace(MountState::Mounting) { MountState::Unmounted(this) => { @@ -312,10 +300,8 @@ where let mounted = match reform { Reform::Keep(type_id, mounted) => { - // Send properties update when component still be rendered. - // But for the first initialization mount gets initial - // properties directly without this channel. - this.replace(type_id, mounted, env.clone()) + // Send properties update when the component is already rendered. + this.replace(type_id, mounted, parent_scope.clone()) } Reform::Before(before) => { // This is a workaround, because component should be mounted @@ -338,7 +324,7 @@ where } } let node = element.as_node().to_owned(); - this.mount(parent, node, env.clone()) + this.mount(parent, node, parent_scope.clone()) } }; @@ -354,8 +340,20 @@ where } } -impl PartialEq for VComp { - fn eq(&self, other: &VComp) -> bool { +impl PartialEq for VComp { + fn eq(&self, other: &VComp) -> bool { self.type_id == other.type_id } } + +impl fmt::Debug for VComp { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str("VComp<_>") + } +} + +impl fmt::Debug for VChild { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str("VChild<_,_>") + } +} diff --git a/src/virtual_dom/vlist.rs b/src/virtual_dom/vlist.rs index 66c7aad39..18fd3b16f 100644 --- a/src/virtual_dom/vlist.rs +++ b/src/virtual_dom/vlist.rs @@ -4,7 +4,7 @@ use crate::html::{Component, Scope}; use stdweb::web::{Element, Node}; /// This struct represents a fragment of the Virtual DOM tree. -#[derive(Debug)] +#[derive(Debug, PartialEq)] pub struct VList { /// The list of children nodes. Which also could have their own children. pub children: Vec>, @@ -46,7 +46,7 @@ impl VDiff for VList { parent: &Element, previous_sibling: Option<&Node>, ancestor: Option>, - env: &Scope, + parent_scope: &Scope, ) -> Option { // Reuse previous_sibling, because fragment reuse parent let mut previous_sibling = previous_sibling.cloned(); @@ -81,11 +81,16 @@ impl VDiff for VList { loop { match (lefts.next(), rights.next()) { (Some(left), Some(right)) => { - previous_sibling = - left.apply(parent, previous_sibling.as_ref(), Some(right), &env); + previous_sibling = left.apply( + parent, + previous_sibling.as_ref(), + Some(right), + &parent_scope, + ); } (Some(left), None) => { - previous_sibling = left.apply(parent, previous_sibling.as_ref(), None, &env); + previous_sibling = + left.apply(parent, previous_sibling.as_ref(), None, &parent_scope); } (None, Some(ref mut right)) => { right.detach(parent); diff --git a/src/virtual_dom/vnode.rs b/src/virtual_dom/vnode.rs index 701763ecd..cc6ac491c 100644 --- a/src/virtual_dom/vnode.rs +++ b/src/virtual_dom/vnode.rs @@ -46,13 +46,21 @@ impl VDiff for VNode { parent: &Element, previous_sibling: Option<&Node>, ancestor: Option>, - env: &Scope, + parent_scope: &Scope, ) -> Option { match *self { - VNode::VTag(ref mut vtag) => vtag.apply(parent, previous_sibling, ancestor, env), - VNode::VText(ref mut vtext) => vtext.apply(parent, previous_sibling, ancestor, env), - VNode::VComp(ref mut vcomp) => vcomp.apply(parent, previous_sibling, ancestor, env), - VNode::VList(ref mut vlist) => vlist.apply(parent, previous_sibling, ancestor, env), + VNode::VTag(ref mut vtag) => { + vtag.apply(parent, previous_sibling, ancestor, parent_scope) + } + VNode::VText(ref mut vtext) => { + vtext.apply(parent, previous_sibling, ancestor, parent_scope) + } + VNode::VComp(ref mut vcomp) => { + vcomp.apply(parent, previous_sibling, ancestor, parent_scope) + } + VNode::VList(ref mut vlist) => { + vlist.apply(parent, previous_sibling, ancestor, parent_scope) + } VNode::VRef(ref mut node) => { let sibling = match ancestor { Some(mut n) => n.detach(parent), diff --git a/src/virtual_dom/vtag.rs b/src/virtual_dom/vtag.rs index ee2b146b2..cc9e42434 100644 --- a/src/virtual_dom/vtag.rs +++ b/src/virtual_dom/vtag.rs @@ -373,7 +373,7 @@ impl VDiff for VTag { parent: &Element, previous_sibling: Option<&Node>, ancestor: Option>, - env: &Scope, + parent_scope: &Scope, ) -> Option { assert!( self.reference.is_none(), @@ -456,7 +456,7 @@ impl VDiff for VTag { } for mut listener in self.listeners.drain(..) { - let handle = listener.attach(&element, env.clone()); + let handle = listener.attach(&element, parent_scope.clone()); self.captured.push(handle); } @@ -469,7 +469,7 @@ impl VDiff for VTag { match (self_children.next(), ancestor_children.next()) { (Some(left), right) => { previous_sibling = - left.apply(&element, previous_sibling.as_ref(), right, &env); + left.apply(&element, previous_sibling.as_ref(), right, &parent_scope); } (None, Some(ref mut right)) => { right.detach(&element);