flammarion 0.0.8 → 0.0.9

data/lib/flammarion.rb

@@ -103,6 +103,8 @@ module Flammarion
       nil
     end
 
+    # Creates a new pane, and resizes the existing panes to fit it.
+    # @param name [String] The name of the pane.
     def pane(name)
       return Pane.new(self, name)
     end

data/lib/flammarion/version.rb

@@ -1,3 +1,3 @@
 module Flammarion
-  VERSION = "0.0.8"
+  VERSION = "0.0.9"
 end

data/lib/flammarion/writeable.rb

@@ -39,41 +39,81 @@ module Flammarion
       end
     end
 
+    # @!macro [new] escape_options
+    #  @option options [Boolean] :raw (false) Perform no escaping at all.
+    #  @option options [Boolean] :colorize (true) Translate ANSI color escape
+    #   codes into displayable colors.
+    #  @option options [Boolean] :escape_html (true) Renders any html tags as
+    #   plain text. If false, allows any arbitrary html to be rendered in the
+    #   writeable area.
+    #  @option options [Boolean] :escape_icons (false) If true, will translate
+    #   any text between two `:` into a font-awesome icon. (E.g. :thumbs-up:)
+
+    # @!macro [new] string_representation
+    #   The string can be included in text for text-accepting methods (such as
+    #   +#puts+, +#table+, etc).
+    #   @note Don't forget to set the :escape_html option to false when including
+    #    this string.
+
     def send_json(hash)
       @front_end.send_json({target: @pane_name}.merge(hash))
     end
 
+    # Adds text to the writeable area without appending a newline.
+    # @param str [String] The text to append
+    # @macro escape_options
     def send(str, options = {})
       @front_end.send_json({action:'append', text:str, target:@pane_name}.merge(options))
     end
     alias_method :print, :send
 
+    # Adds text to the writeable area and appends a newline.
+    # @param str [String] The text to append
+    # @macro escape_options
     def puts(str = "", options = {})
       send str, options
       send "\n"
       return nil
     end
 
+    # Replaces the contents of the writeable area with text
+    # @param str [String] The text to append
+    # @macro escape_options
     def replace(str, options = {})
       send_json({action:'replace', text:str}.merge(options))
       return nil
     end
 
+    # Clears the contents of the writeable area
     def clear
       send_json({action:'clear'})
       return nil
     end
 
+    # Closes the pane or window
     def close
       send_json({action:'closepane'})
+      return nil
     end
 
+    # Creates a new plot to display single axis data
+    # @param [Array<Number>] values A list of numbers to plot
+    # TODO: @options
+    # @return [Spectrum] A Spectrum object for manipulation after creation.
     def plot(values, options = {})
       id = @front_end.make_id
       send_json({action:'plot', data:values, id:id}.merge(options))
       return Spectrum.new(id, @pane_name, @front_end)
     end
 
+    # @overload highlight(data, options)
+    #   Adds a pretty-printed, highlighted display of data
+    #   @param text [Hash, Array] A dataset to be displayed
+    #   @macro escape_options
+    # @overload highlight(text, options)
+    #   Adds syntax-highlighted text or code to the writeable area
+    #   @param text [String] Code to be highlighed
+    #   @macro escape_options
     def highlight(text, options = {})
       output = text
       output = JSON.pretty_generate(text) if text.is_a? Hash or text.is_a? Array
@@ -81,6 +121,12 @@ module Flammarion
       nil
     end
 
+    # Adds a clickable button which will call +block+ when clicked
+    # @param label [String] The text of the button
+    # @option options [Boolean] :inline (false) If true, creates a small button
+    #    embedded in the text. If false, creates a button that spans the width
+    #    of the writeable area.
+    # @macro escape_options
     def button(label, options = {}, &block)
       id = @front_end.make_id
       send_json({action:'button', label:label, id:id}.merge(options))
@@ -88,22 +134,63 @@ module Flammarion
       id
     end
 
+    # Creates a string representing a button  will call the given block when it
+    # is clicked.
+    # @macro string_representation
+    # @param label [String] The label on the button
+    # @return A string representing the html for the button.
     def embedded_button(label, options = {}, &block)
       id = @front_end.make_id
       @front_end.callbacks[id] = block
       %|<a class="floating-button" href="#" onClick="$ws.send({id:'#{id}', action:'callback', source:'embedded_button'})">#{label}</a>|
     end
 
+    # Creates a string representing a hyperlink that when clicked will call the
+    # given block.
+    # @macro string_representation
+    # @param label [String] The text to become the link
+    # @return a string representing the html for the link.
     def callback_link(label, options = {}, &block)
       id = @front_end.make_id
       @front_end.callbacks[id] = block
       %|<a href="#" onClick="$ws.send({id:'#{id}', action:'callback', source:'link'})">#{label}</a>|
     end
 
+    # Creates a string representing a Font Awesome icon.
+    # @macro string_representation
+    # @param name [String] The name of a Font Awesome icon class. See
+    # @see https://fortawesome.github.io/Font-Awesome/icons/ for the list.
     def icon(name, additional_classes = [])
       %|<i class="fa fa-#{name} #{additional_classes.collect{|c| "fa-#{c}"}.join(" ")}"></i>|
     end
 
+    # Creates a new text-input field into which the user can enter text.
+    # If a block is given, the block will be called when ever the text is
+    # changed. If a block is not given, it will return a DeferredValue object
+    # which can be used to get the value at any time.
+    # @param label [String] The displayed placeholder text for the input. This
+    #  does not set the actual value of the input field or the returned
+    #  +DeferredValue+. Use the +:value+ option for that.
+    # @option options [Boolean] :multiline (false) Creates a large text box if
+    #  true; otherwise creates a single line input box.
+    # @option options [Boolean] :autoclear (false) Automatically clears the
+    #  input field every time the user changes the value. The callback will only
+    #  be called for user initiated changes, not for auto-clear changes.
+    # @option options [String] :value Sets the starting value of the field and
+    #  the returned +DeferredValue+.
+    # @option options [Boolean] :once (false) If true, then the input box will
+    #  be converted into a normal line of text once the user has changed it.
+    #  The callback will still be called, but the user will no longer be able
+    #  to change the text.
+    # @option options [Boolean] :keep_label (false) If +:once+ is also set, this
+    #  will prepend +label+ when converting the input to plain text.
+    # @overload input(label, options = {})
+    #  @return [DeferredValue] An object representing the current value of the
+    #   input, which can be converted to text using +#to_s+.
+    # @overload input(label, options = {})
+    #  @yield [message_hash] Invokes the block every time the text changes. The
+    #   new text of the input can be obtained from the +"text"+ key of the
+    #   +message_hash+.
     def input(label, options = {}, &block)
       id = @front_end.make_id
       send_json({action:'input', label:label, id:id}.merge(options))
@@ -116,6 +203,16 @@ module Flammarion
       end
     end
 
+    # Creates a new checkbox which the user can click.
+    # @param label [String] The placeholder text for the input
+    # @macro escape_options
+    # @overload checkbox(label, options = {})
+    #  @return [DeferredValue] An object representing the current value of the
+    #   checkbox. Use +#checked?+ to get the state of the checkbox.
+    # @overload checkbox(label, options = {})
+    #  @yield [message_hash] Invokes the block every time the checkbox is
+    #   toggled. Use the "checked" field of +message_hash+ to get the new state
+    #   of the checkbox.
     def checkbox(label, options = {}, &block)
       id = @front_end.make_id
       send_json({action:'checkbox', label:label, id:id}.merge(options))
@@ -129,10 +226,12 @@ module Flammarion
       end
     end
 
+    # Adds a horizontal rule
     def break(options = {})
       send_json({action:'break'}.merge(options))
     end
 
+    # Adds raw html
     def html(data)
       send_json({action:'replace', text:data, raw:true})
     end
@@ -189,7 +288,7 @@ module Flammarion
       send_json({action:'reorient', orientation:orientation})
     end
 
-    def button_box(name)
+    def button_box(name = "buttonbox")
       send_json({action:'buttonbox', name:name})
       return Pane.new(@front_end, name)
     end

data/lib/html/build/javascripts/actions.js

@@ -205,7 +205,7 @@ void 0===c?d&&"get"in d&&null!==(e=d.get(a,b))?e:(e=n.find.attr(a,b),null==e?voi
       element.append(this.__parent.escape(data.text, data));
       results = [];
       while (element.hasClass("pane")) {
-        atBottom = atBottomStack.pop();
+        atBottom = atBottomStack.shift();
         if (atBottom) {
           element.scrollTop(element[0].scrollHeight - element.height() - marginSize);
         }

data/lib/html/build/javascripts/all.js

@@ -6826,7 +6826,7 @@ if (typeof module !== 'undefined') {
       element.append(this.__parent.escape(data.text, data));
       results = [];
       while (element.hasClass("pane")) {
-        atBottom = atBottomStack.pop();
+        atBottom = atBottomStack.shift();
         if (atBottom) {
           element.scrollTop(element[0].scrollHeight - element.height() - marginSize);
         }

data/lib/html/source/javascripts/actions.coffee

@@ -15,7 +15,7 @@ $.extend WSClient.prototype.actions,
     element.append(@__parent.escape(data.text, data))
 
     while element.hasClass("pane")
-      atBottom = atBottomStack.pop()
+      atBottom = atBottomStack.shift()
       element.scrollTop(element[0].scrollHeight - element.height() - marginSize) if atBottom
       element = element.parent()
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flammarion
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.0.9
   prerelease: 
 platform: ruby
 authors: