correspondence-markup 0.3.0 → 0.3.1

data/lib/correspondence-markup.rb

@@ -5,11 +5,18 @@ require 'correspondence-markup/bracketed-grammar'
 
 module CorrespondenceMarkup
   
+  # Compiler than parses and compiles correspondence markup source code 
+  # into an array of StructureGroup objects (from which HTML can be
+  # generated in the format required by correspondence.js)
   class CorrespondenceMarkupCompiler
+    
+    # initialize by creating the CorrespondenceMarkupLanguageParser (defined by the Treetop source)
     def initialize
       @parser = CorrespondenceMarkupLanguageParser.new
     end
     
+    # compile source code into an array of StructureGroups, 
+    # throwing an exception if there is a parse error
     def compile_structure_groups(markup)
       syntax_tree = @parser.parse(markup, root: :structure_groups)
       if(syntax_tree.nil?)
@@ -19,8 +26,4 @@ module CorrespondenceMarkup
     end
   end
   
-  def self.sayHello
-    "hello"
-  end
-  
 end

data/lib/correspondence-markup/bracketed-grammar.treetop

@@ -1,21 +1,49 @@
 require "correspondence-markup/types"
 
+# Grammar for a markup language which can be compiled into HTML format
+# required by correspondence.js
+
+# General note on bracketing of sequences - different components are enclosed
+# by different types of bracket, in particular:
+#
+# * item: "[]"
+# * item-group: "[]"
+# * structure: "{}"
+# * structure group: "()"
+#
+# However, in anticipation of a UI where the user may choose the granularity
+# at which to edit components of particular content, the parsing of brackets
+# is handled by the parent component, e.g. the "{}" bracketing of structures
+# is specified in the grammar rule for structure_group.
+# For example, if a user is editing a structure definition in a UI text area, 
+# there should be no necessity for the user to enter the enclosing "{}" brackets, 
+# because the UI text area implicitly encloses the definition that the user is editing.
+
 grammar CorrespondenceMarkupLanguage
 
+  # Include the Module containing Ruby classes representing the AST nodes
   include CorrespondenceMarkup
 
+  # This rule defines a sequence of structure groups.
+  # Individual structure groups are independent of each other
+  # (although typically they will be a sequence of structure groups
+  # where each structure group has structures in the same sequence of languages).
   rule structure_groups
     s groups:("(" structure_group ")" s)*
     {
+      # Return an array of StructureGroup object
       def value
         groups.elements.map {|e| e.structure_group.value}
       end
     }
   end
 
+  # A structure group is a group of structures where each structure represents
+  # the same information in a different "language".
   rule structure_group
     s description:structure_group_description? s structures:("{" structure "}" s)*
     { 
+      # Return a StructureGroup
       def value
         structureObjects = structures.elements.map {|e| e.structure.value}
         CorrespondenceMarkup::StructureGroup.new(structureObjects)
@@ -23,13 +51,23 @@ grammar CorrespondenceMarkupLanguage
     }
   end
   
+  # Optional lengthy description of a particular structure group. 
+  # (Intended to be displayed as the title of the structure group
+  # describing the information presented in the structure group.)
   rule structure_group_description
     "#" s [^{\n]* "\n"
   end
 
+  # A structure is one of two or more structures in a structure group
+  # (although the grammar does not impose any count restriction, in anticipation
+  # of application user's editing and saving incomplete content).
+  # A structure has a "type" (short language description intended to map to a CSS class), 
+  # a "description" (longer but still concise language description for display to the reader)
+  # and a sequence of "item groups".
   rule structure
     structure_annotation s itemGroups:("[" item_group "]" s)*
     { 
+      # Return a Structure
       def value
         itemGroupObjects = itemGroups.elements.map {|e| e.item_group.value}
         class_name, description = structure_annotation.value
@@ -38,14 +76,17 @@ grammar CorrespondenceMarkupLanguage
       end
     }
   end
-  
+
+  # Structure class (for the structure's "type"), with rules similar to those of a CSS class identifier.
   rule structure_class
     ([a-zA-Z] [a-zA-Z0-9_-]*)?
   end
 
+  # Structure annotation contains the "type" and the "description" (both optional)
   rule structure_annotation
     structure_class description_section:(":" s description:[^\n]* "\n")?
     {
+      # Return an array of two strings for the type and the description
       def value
         class_name = structure_class.text_value
         description = nil
@@ -57,9 +98,16 @@ grammar CorrespondenceMarkupLanguage
     }
   end
 
+  # An item group is a sub-structure of a structure which contains a sequence of items and "non-items".
+  # An item group has an upper-case alphabetic ID (which should be unique within a structure, 
+  # and which should be the ID of an item-group in the first structure of a structure group, but
+  # neither of these rules is required by the grammar).
+  # The item group ID is used as a default prefix for any item IDs that do not start with 
+  # alphabetic characters (so a full item ID is always alphabetic followed by something else).
   rule item_group
     optional_id:(id:[A-Z]* ":")? components:(item / non_item)*
     { 
+      # Return an ItemGroup
       def value
         group_id = optional_id.elements ? optional_id.elements[0].text_value : ""
         componentObjects = components.elements.map {|e| e.value(group_id)}
@@ -68,18 +116,37 @@ grammar CorrespondenceMarkupLanguage
     }
   end
   
+  # A "non-item" is textual content in an item group that is not part of an actual item.
+  # In effect this is text which is either not translatable to content in other structures
+  # in the same structure group, or, it is considered unimportant to identify its translation.
+  # For example, in the second case, punctuation in sentences, where translation is reasonably obvious, and we
+  # wish to highlight the translations of the actual words.
   rule non_item
     text:text
     { 
+      # Given the item group ID (as a default prefix for the item IDs, which is ignored for non-items), 
+      # return a NonItem.
       def value(group_id = "")
         CorrespondenceMarkup::NonItem.new(text.value)
       end
     }
   end
 
+  # An item is textual content with an ID, where different items in the same structure group
+  # with the same ID are considered to be related to each other.
+  # Typically, items with the same ID in the same structure are considered to be part of the
+  # "same item", and items with the same ID in different structures are considered to be
+  # translations of each other.
+  # Item IDs consists of an upper-case alphabetic prefix followed by a numeric ID.
+  # Any item ID that lacks an alphabetic prefix will have the item group ID of the containing
+  # item group added as a prefix to its ID.
+  # (This reflects the assumption that an item usually relates to items in item groups in other
+  # structures with the same item group ID, but occasionally an item relates to an item in
+  # some other item group in another structure.)
   rule item
     "[" id:item_ids S text:text "]"
     { 
+      # Given the item group ID (as a default prefix for the item IDs), return an Item
       def value(group_id = "")
         item_ids = id.text_value.split(",")
         item_ids = item_ids.map { |item_id| item_id.match(/[A-Z]/) ? item_id : group_id + item_id}
@@ -88,27 +155,38 @@ grammar CorrespondenceMarkupLanguage
     }
   end
 
+  # Text is the textual component of both items and non-items.
+  # Text is delimited by "]", "[" and (at the beginning of items) whitespace.
+  # Text can include backslash-quoted characters, for example to include any of the delimiter characters.
   rule text
     (("\\" .) / (![\[\]\\] .))+
     { 
+      # Return the text, de-quoting any backslash-quoted characters.
       def value
         text_value.gsub(/\\(.)/, '\1')
       end
     }
   end
   
+  # Items can actually have multiple IDs, in which case they are separated by commas
+  # (and no whitespace). If there are multiple IDs, the convention of applying the
+  # item group ID as a default prefix is applied individually to each ID.
+  # So, for example, "2,A2,3" in item group B would be expanded to "B2,A2,B3".
   rule item_ids
     item_id ("," item_id)*
   end
 
+  # An item ID - optional upper-case alphabetic prefix, followed by a numeric ID.
   rule item_id
     [A-Z]* [0-9]+
   end
   
+  # Rule for optional whitespace
   rule s
     [\s\n\r\t]*
   end
 
+  # Rule for mandatory whitespace
   rule S
     [\s\n\r\t]+
   end

data/lib/correspondence-markup/types.rb

@@ -1,17 +1,31 @@
 
 require 'cgi'
 
+# Module containing the Ruby classes that define the nodes of the AST 
+# created when parsing Correspondence-Markup language according to the
+# grammar defined by *bracketed-grammar.treetop*.
+# Each node class knows how to output itself as HTML as defined by the
+# method *to_html*.
 module CorrespondenceMarkup
-  
+
+  # Helper functions used when generating HTML
   module Helpers
     
     # Either 1: a tag enclosed in "<" & ">", possibly missing the ">", or, 2: text outside a tag
     TAGS_AND_TEXT_REGEX = /([<][^>]*[>]?)|([^<]+)/
     
+    # Split some HTML source into tags and plain text not in tags
+    # (so that the two can be processed differently, e.g. applying a transformation to text content
+    # where you don't want the transformation to apply to the internals of a directly-coded HTML tag)
     def self.split_tags_and_text(html)
       html.scan(TAGS_AND_TEXT_REGEX).to_a
     end
     
+    # Convert text content into HTML according to various true/false options.
+    # Note: the text may contain HTML tags
+    # * escaped: if true, HTML-escape the text
+    # * br: if true, convert end-of-line characters to <br/> tags
+    # * nbsp: if true, convert all spaces in the text that is not in tags into &nbsp;
     def text_to_html(text, options)
       html = text
       if options[:escaped]
@@ -31,88 +45,145 @@ module CorrespondenceMarkup
   end
   
   # An item is text in a structure with an associated id
+  # Typically if would be a word in a sentence. Items are to 
+  # be related to other items in other structures in the same
+  # structure group that have the same ID (also to other items
+  # in the same structure with the same ID).
   class Item
+    
     include Helpers
     
-    attr_reader :id, :text
+    # The ID, which identifies the item (possibly not uniquely) within a given structure
+    attr_reader :id
     
+    # The text of the item
+    attr_reader :text
+
+    # Initialize from ID and text
     def initialize(id, text)
       @id = id
       @text = text
     end
     
+    # Is this an item? (yes)
     def item?
       true
     end
     
+    # An item is equal to another item with the same ID and text
     def ==(otherItem)
       otherItem.class == Item && otherItem.id == @id && otherItem.text == @text
     end
     
+    # Convert to HTML as a *<span>* element with *data-id* attribute set to the ID
+    # according to options for Helpers::text_to_html
     def to_html(options={})
       text_html = text_to_html(@text, options)
       "<span data-id=\"#{@id}\">#{text_html}</span>"
     end
   end
   
-  # A non-item is text in a structure that is not an item - it is just text
+  # A non-item is some text in a structure that is not an item - it will
+  # not be related to any other text.
   class NonItem
     include Helpers
     
+    # The text of the non-item
     attr_reader :text
     
+    # Initialize from text
     def initialize(text)
       @text = text
     end
     
+    # Is this an item? (no)
     def item?
       false
     end
     
+    # A non-item is equal to another non-item with the same text
     def ==(otherNonItem)
       otherNonItem.class == NonItem && otherNonItem.text == @text
     end
     
+    # Convert to HTML according to options for Helpers::text_to_html
     def to_html(options={})
       text_to_html(@text, options)
     end
   end
   
   # A group of items & non-items that will form part of a structure
+  # Typically an item group is one line of items (words), or maybe
+  # two or three lines which naturally group together within the
+  # overall structure.
+  # Item groups with the same ID in different structures in the same
+  # structure group related to each other, and may be shown next
+  # to each other in the UI when the "Interleave" option is chosen.
+  # (An "item group" could also be regarded as a "sub-structure".)
   class ItemGroup
-    attr_reader :id, :content
     
+    # The ID which is unique in the structure. It identifies the 
+    # item group uniquely within the structure. It also serves as a default
+    # prefix when parsing IDs for individual items.
+    attr_reader :id
+    
+    # The array of items and non-items
+    attr_reader :content
+    
+    # Initialize from ID and array of items and non-items
     def initialize(id, content)
       @id = id
       @content = content
     end
 
+    # An item group is equal to another item group with the same IDs and the same content
     def ==(otherItemGroup)
       otherItemGroup.class == ItemGroup && otherItemGroup.id == @id && otherItemGroup.content == @content
     end
     
+    # Convert to HTML as a *<div>* tag with class *item-group*, *data-group-id* attribute
+    # equal to the ID, and containing the HTML output for the content items and non-items
+    # (with those converted according to the options for Helpers::text_to_html).
     def to_html(options={})
       "<div class=\"item-group\" data-group-id=\"#{@id}\">\n  " + 
         @content.map{|x| x.to_html(options)}.join("") + "\n</div>\n"
     end
   end
   
-  # A structure, containing a sequence of items and non-items
+  # A structure, containing a sequence of item groups, as well as a type and a description.
+  # A structure will be one of two or more in a "structure group".
   class Structure
-    attr_reader :type, :description, :item_groups
     
+    # A short alphanumeric name for the type, typically reflecting the "language" of a structure
+    # where different structures in a group are different language versions of the same information.
+    # It is used to determine a CSS class of the structure. E.g. "english". (It can be nil.)
+    attr_reader :type
+    
+    # A textual description of the type which will be displayed in the UI. E.g. "English".
+    # Ideally it should be relatively concise. Can be nil.
+    attr_reader :description
+    
+    # The array of item groups that make up the content of the structure.
+    attr_reader :item_groups
+    
+    # Initialize from type, description and item groups
     def initialize(type, description, item_groups)
       @type = type
       @description = description
       @item_groups = item_groups
     end
 
+    # A structure is equal to another structure with the same type, description and item groups
     def ==(otherStructure)
       otherStructure.class == Structure && otherStructure.type == @type  &&
         otherStructure.description == description &&
         otherStructure.item_groups == @item_groups
     end
     
+    # From the type, determine the CSS class names to be used in the *<div>* element created
+    # by to_html. If there is no type, then just "structure", otherwise, "structure <type>-structure", 
+    # e.g. if the type is "english",  then "structure english-structure".
+    # (The "-structure" suffix is used to reduce the chance of accidental CSS class name collisions.)
     def css_class_names
       class_names = "structure"
       if @type != "" and @type != nil
@@ -121,6 +192,9 @@ module CorrespondenceMarkup
       class_names
     end
     
+    # Convert to HTML as a *<div>* with CSS class determined by *css_class_names*.
+    # Include a *<div>* of CSS class "language" (if the description is given)
+    # Include HTML for the item groups, converted according to the options for Helpers::text_to_html).
     def to_html(options={})
       itemGroupHtmls = @item_groups.map{|x| x.to_html(options)}
       "<div class=\"#{css_class_names}\">\n  " + 
@@ -130,18 +204,31 @@ module CorrespondenceMarkup
     end
     
   end
-  
+
+  # A structure group is a group of structures. Different structures in one structure group
+  # all represent the same information, but in different "languages". Items different
+  # structures with the same item ID are shown in the UI as being translations of each other.
+  # (Items with the same ID in the same structure are also show as related, and are presumed
+  # to be separated components of a single virtual item.)
   class StructureGroup
+    
+    # The array of structures
     attr_reader :structures
     
+    # Initialize from the structures
     def initialize(structures)
       @structures = structures
     end
 
+    # A structure group is equal to another structure group that has the same structures
     def ==(otherStructureGroup)
       otherStructureGroup.class == StructureGroup && otherStructureGroup.structures == @structures
     end
 
+    # Convert to HTML as a *<div>* of CSS class "structure-group" that contains the HTML
+    # outputs from the structures.
+    # Options for Helpers::text_to_html can be provided as single true/false value, or, as arrays
+    # of values, in which case the individual values are mapped to the corresponding structures.
     def to_html(options={})
       numStructures = structures.length
       structureOptions = Array.new(numStructures)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: correspondence-markup
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-10 00:00:00.000000000 Z
+date: 2013-07-14 00:00:00.000000000 Z
 dependencies: []
 description: Use to generate HTML pages containing structure groups, structures and
   items as used by correspondence.js.
@@ -38,7 +38,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1049094467
+      hash: -1042658257
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: