ppr 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 71f7684269c365ceabde0b9a78723562b4e05557
-  data.tar.gz: 1dd28975ce62b8b8983fbeb300acf8d135c6569b
+  metadata.gz: 9c406b99cf38bd9244827b268c16a331b41f752d
+  data.tar.gz: 213074c919132f292e4edff0e0389c537f3b5349
 SHA512:
-  metadata.gz: 75867d46fd7a09643f1b3c91cc48110ec5f37ce38d8175714fdec7991b2828c19071836deb4c82f9b233294ab812085a061e277380cbe63d77779c5049b6816a
-  data.tar.gz: 22ccdc04aaba51bae61700b8afb5c5ad51308ae47607bfe964605cb96d82c9b515ff6d39fb77e1d5eff8baeb8a4dc38e6714c29f4f64e0884d461c3b9d1b31ed
+  metadata.gz: 4e908bea3122b499442c72844fa5675a0cf58626dc15d2b2437d574f7536e2f6c0861c89d242de5242a97076e4c0d37bf86b2f21a8f2573820b8ea48a1c0479a
+  data.tar.gz: 412ca44eee6324788cd342ff83b75502bb133bb10f933814e403e3933137bb12fd0939a9fe9cbfb340b02811ccb61f9b3a7c6b2c8ab5c99e4eca4de1e15aacd7

data/lib/ppr/keyword_searcher.rb

@@ -2,11 +2,12 @@
 ##              Map class for searching keywords in a text.         ##
 ######################################################################
 
-
+##
+# Tool for looking for keywords within a string.
 class KeywordSearcher
 
-    ## Creates a new keyword searcher, where words are between +seperators+
-    #  regular expressions.
+    # Creates a new keyword searcher, where words are between +seperators+
+    # regular expressions.
     def initialize(separator = "")
         # Checks and set the separator.
         @separator = Regexp.new(separator).to_s
@@ -25,7 +26,7 @@ class KeywordSearcher
         return self
     end
 
-    ## Adds a +keyword+ to the searcher associated with an +object+.
+    # Adds a +keyword+ to the searcher associated with an +object+.
     def []=(keyword,object)
         # Ensure the keyword is a valid string.
         keyword = keyword.to_str
@@ -41,17 +42,17 @@ class KeywordSearcher
         @keyword_extract = Regexp.new(@keywords.join("|"))
     end
 
-    ## Get the object corresponding to +keyword+.
+    # Get the object corresponding to +keyword+.
     def [](keyword)
         return @map[keyword.to_s]
     end
 
-    ## Search a keyword inside a +text+ and return the corresponding object
-    #  if found with the range in the string where it has been found.
+    # Search a keyword inside a +text+ and return the corresponding object
+    # if found with the range in the string where it has been found.
     #
-    #  If a keyword is in +skip+ it s ignored.
+    # If a keyword is in +skip+ it s ignored.
     #
-    #  NOTE: the first found object is returned.
+    # NOTE: the first found object is returned.
     def find(text,skip = [])
         # print "skip=#{skip} @keywords=#{@keywords}\n"
         # Compute the regular expression for finding the keywords.
@@ -78,13 +79,13 @@ class KeywordSearcher
         end
     end
 
-    ## Search each keyword inside a +text+ and apply the block on the
-    #  corresponding objects if found with the range in the string where it
-    #  has been found.
+    # Search each keyword inside a +text+ and apply the block on the
+    # corresponding objects if found with the range in the string where it
+    # has been found.
     #
-    #  Returns an enumerator if no block is given.
+    # Returns an enumerator if no block is given.
     #
-    #  NOTE: keywords included into a longer one are ignored.
+    # NOTE: keywords included into a longer one are ignored.
     def each_in(text)
         return to_enum(:each_in,text) unless block_given?
         # Check and clone the text to avoid side effects.

data/lib/ppr/ppr_core.rb

@@ -8,38 +8,42 @@ require "ppr/keyword_searcher.rb"
 module Ppr
 
 
-    ## Converts a +name+ to an attribute symbol.
+    ## 
+    # Converts a +name+ to an attribute symbol.
     def Ppr.to_attribute(name)
         name = name.to_s
         (name.start_with?("@") ? name : "@" + name).to_sym
     end
 
-## Describes a storage for line number
+##
+# Describes a storage for line number
 class LineNumber < SimpleDelegator
-    ## Creates a new storage for line number +num+.
+    # Creates a new storage for line number +num+.
     def initialize(num)
         super(num.to_i)
     end
 
-    ## Sets the line number to +num+.
+    # Sets the line number to +num+.
     def set(num)
         __setobj__(num.to_i)
     end
 end
 
 
-## Describes a macro of the ruby preprocessor.
+##
+# Describes a macro of the ruby preprocessor.
 class Macro
 
-    ## The name of the macro.
+    # The name of the macro.
     attr_reader :name
 
-    ## Creates a new macro named +name+, starting at line number +num+,
-    #  generated from preprocessor +ppr+ and with possible +variables+.
-    #  
-    #  The +expand+ strings can be redefined through keyword arguments.
-    #  The +final+ flag indicates that the result of the macro expansion
-    #  shall not be preprocessed again.
+    # Creates a new macro named +name+, starting at line number +num+,
+    # generated from preprocessor +ppr+ and with possible +variables+.
+    #
+    # Other parameters:
+    # +expand+:: used to redefine the expand operator
+    # +final+:: indicates that the result of the macro expansion
+    # shall not be preprocessed again.
     def initialize(name, num, ppr, *variables, expand: ":<", final: true)
         # Check and set the name.
         @name = name.to_str
@@ -82,13 +86,13 @@ class Macro
             #}}} This comment is just to avoid confusing the text editor.
     end
 
-    ## Tells if the maco expansion result is final (i.e. it is not preprocessed
-    #  again) or not.
+    # Tells if the maco expansion result is final (i.e., it is not preprocessed
+    # again) or not.
     def final?
         return @final
     end
 
-    ## Adds a +line+ to the macro.
+    # Adds a +line+ to the macro.
     def add(line)
         # Process the line.
         # Remove the ending newline if any.
@@ -96,13 +100,13 @@ class Macro
     end
     alias << add
 
-    ## Checks if the macro is empty (no code line yet).
+    # Checks if the macro is empty (no code line yet).
     def empty?
         return @lines.empty?
     end
 
-    ## Generates the code of the macro invoked at line number +i_number+
-    #  using +values+ for the variables.
+    # Generates the code of the macro invoked at line number +i_number+
+    # using +values+ for the variables.
     def generate(i_number,*values)
         # First generate a variable for the resulting text.
         result = "result_"
@@ -140,13 +144,13 @@ class Macro
 
     # Methods used by apply for handling exception messages.
     
-    ## Regular expression for identifying a line number inside an exception
-    #  message
+    # Regular expression for identifying a line number inside an exception
+    # message.
     E_NUMBER = /:[1-9][0-9]*:/ 
-    ## Type of exception which correspond to a macro execution.
+    # Type of exception which correspond to a macro execution.
     E_TYPE = /\(eval\)\s*/
     
-    ## Tells if an exception +message+ includes a line number.
+    # Tells if an exception +message+ includes a line number.
     def e_number(message)
         found = E_NUMBER.match(message)
         if found then
@@ -158,12 +162,12 @@ class Macro
         end
     end
 
-    ## Tells if an exception message is of a given +type+.
+    # Tells if an exception message is of a given +type+.
     def e_type?(message,type)
         return message =~ Regexp.new(type)
     end
 
-    ## Shifts the line number inside an exception +message+ by +sh+.
+    # Shifts the line number inside an exception +message+ by +sh+.
     def e_shift_number(message,sh)
         # Edit the message to fix the line number and raise then.
         return message.gsub(E_NUMBER) { |str|
@@ -181,8 +185,8 @@ class Macro
         }
     end
 
-    ## Update an exception +message+ to refer macro +name+ invoked at line
-    #  number +i_number+ and adds a possible macro line +number+.
+    # Update an exception +message+ to refer macro +name+ invoked at line
+    # number +i_number+ and adds a possible macro line +number+.
     def Macro.e_message(name, message, i_number, number = nil)
         result = "Ppr error (#{name}:#{i_number})"
         result << ":#{number}: " if number
@@ -190,13 +194,13 @@ class Macro
         return result
     end
 
-    ## Update an exception +message+ to refer the macro invoked at line number
-    #  +i_number+ and adds a possible macro line +number+.
+    # Update an exception +message+ to refer the macro invoked at line number
+    # +i_number+ and adds a possible macro line +number+.
     def e_message(message, i_number, number = nil)
         Macro.e_message(@name,message,i_number,number)
     end
 
-    ## Applies the macro invoked at line number +i_number+ with +arguments+.
+    # Applies the macro invoked at line number +i_number+ with +arguments+.
     def apply(i_number,*arguments)
         # Generate the code of the macro.
         code = self.generate(i_number,*arguments)
@@ -261,20 +265,22 @@ class Macro
 end
 
 
-## Describes an assignment macro of the ruby preprocessor.
+## 
+# Describes an assignment macro of the ruby preprocessor.
 class Assign < Macro
-    ## Creates a new assignment macro whose assigned variable is +var+,
-    #  starting at line number +num+ generated from preprocessor +ppr+.
-    #  
-    #  The +expand+ strings be redefined through keyword arguments.
+    # Creates a new assignment macro whose assigned variable is +var+,
+    # starting at line number +num+ generated from preprocessor +ppr+.
+    # 
+    # Other parameters:
+    # +expand+:: redefines the expand operator string.
     def initialize(name, num, ppr, expand: ":<")
         super(name,num,ppr,expand: expand)
         # Creates the attribute which will be assigned.
         @var_sym = Ppr.to_attribute(name)
     end
 
-    ## Applies the macro invoked at line number +i_number+,
-    #  its result in assigned to the class variable.
+    # Applies the macro invoked at line number +i_number+,
+    # its result in assigned to the class variable.
     def apply(i_number)
         # Expands the macro.
         line = super(i_number)
@@ -285,17 +291,18 @@ class Assign < Macro
     end
 end
 
-## Descibes an abstract class for loading or requiring files.
+## 
+# Descibes an abstract class for loading or requiring files.
 class LoadRequire < Macro
-    ## Creates a new load or require macro starting at line number +num+
-    #  generated from preprocessor +ppr+.
-    #  
-    #  The +expand+ strings be redefined through keyword arguments.
+    # Creates a new load or require macro starting at line number +num+
+    # generated from preprocessor +ppr+.
+    # 
+    # The +expand+ strings be redefined through keyword arguments.
     def initialize(num, ppr, expand: ":<")
         super("",num,ppr,expand: expand)
     end
 
-    ## Loads and preprocess file +name+.
+    # Loads and preprocess file +name+.
     def loadm(name)
         output = StringIO.new("")
         # print "name=#{name}\n"
@@ -306,10 +313,11 @@ class LoadRequire < Macro
     end
 end
 
-## Describes a macro loading and pasting a file into the current one.
+##
+# Describes a macro loading and pasting a file into the current one.
 class Load < LoadRequire
-    ## Applies the macro invoked at line number +i_number+,
-    #  its result is the name of the file to be loaded.
+    # Applies the macro invoked at line number +i_number+,
+    # its result is the name of the file to be loaded.
     def apply(i_number)
         # Expand the macro, its result is the name of the file to load.
         name = super(i_number)
@@ -320,13 +328,13 @@ class Load < LoadRequire
     end
 end
 
-## Describes a macro loading and pasting a file into the current one
-#  only if it has not already been loaded before.
+# Describes a macro loading and pasting a file into the current one
+# only if it has not already been loaded before.
 class Require < LoadRequire
     @@required = [] # The already required files.
 
-    ## Applies the macro invoked at line number +i_number+,
-    #  its result is the name of the file to be loaded if not already loaded.
+    # Applies the macro invoked at line number +i_number+,
+    # its result is the name of the file to be loaded if not already loaded.
     def apply(i_number)
         # Expand the macro, its result is the name of the file to load.
         name = super(i_number)
@@ -343,36 +351,38 @@ class Require < LoadRequire
     end
 end
 
-## Describes a conditional macro.
+##
+# Describes a conditional macro.
 class If < Macro
-    ## Creates a new load or require macro starting at line number +num+
-    #  generated from preprocessor +ppr+.
-    #  
-    #  The +expand+ strings be redefined through keyword arguments.
+    # Creates a new load or require macro starting at line number +num+
+    # generated from preprocessor +ppr+.
+    # 
+    # The +expand+ strings be redefined through keyword arguments.
     def initialize(num, ppr, expand: ":<")
         super("",num,ppr,expand: expand)
     end
 end
 
 
-## Describes the ruby preprocessor.
+##
+# Describes the ruby preprocessor.
 #
-#  Usage:
+# Usage:
 #         ppr = Ppr::Preprocessor.new(<some options>)
 #         ppr.preprocess(<some input stream>, <some output stream>)
 class Preprocessor
 
-    ## Creates a new preprocessor, where +apply+, +applyR+, +define+, +defineR+,
-    #  +assign+, +loadm+, +requirem+, +ifm+, +elsem+ and +endm+ are the
-    #  keywords defining the beginings and end of a macro definitions,
-    #  and where +separator+ is the regular expression used for
-    #  separating macro references to the remaining of the code, +expand+ is
-    #  the string representing the expansion operator of the macro, +glue+ is
-    #  string used for glueing a macro expension to the text,
-    #  +escape+ is the escape character.
+    # Creates a new preprocessor, where +apply+, +applyR+, +define+, +defineR+,
+    # +assign+, +loadm+, +requirem+, +ifm+, +elsem+ and +endm+ are the
+    # keywords defining the beginings and end of a macro definitions,
+    # and where +separator+ is the regular expression used for
+    # separating macro references to the remaining of the code, +expand+ is
+    # the string representing the expansion operator of the macro, +glue+ is
+    # string used for glueing a macro expension to the text,
+    # +escape+ is the escape character.
     #
-    #  Assigned parameters can be added through +param+ to be used within 
-    #  the macros of the preprocessed text.
+    # Assigned parameters can be added through +param+ to be used within 
+    # the macros of the preprocessed text.
     def initialize(params = {},
                    apply: ".do", applyR: ".doR", 
                    define: ".def", defineR: ".defR",
@@ -447,27 +457,27 @@ class Preprocessor
 
     # Methods for handling the execution context of the macros.
 
-    ## Executes a macro in a safe context.
+    # Executes a macro in a safe context.
     def run(&proc)
         @generator.run do |__stream__|
             @context.instance_exec(__stream__,&proc) 
         end
     end
 
-    ## Sets parameter +param+ to +value+.
+    # Sets parameter +param+ to +value+.
     def parameter_set(param,value)
         # print "Setting #{Ppr.to_attribute(param)} with #{value.to_s}\n"
         @context.instance_variable_set(Ppr.to_attribute(param),value.to_s)
     end
 
-    ## Gets the value of parameter +param.
+    # Gets the value of parameter +param.
     def parameter_get(param)
         return @context.instance_variable_get(Ppr.to_attribute(param))
     end
 
     # Methods for parsing the lines.
     
-    ## Restores a +string+ whose begining may have been glued.
+    # Restores a +string+ whose begining may have been glued.
     def unglue_front(string)
         if string.start_with?(@glue) then
             # There is a glue, so remove it.
@@ -479,7 +489,7 @@ class Preprocessor
         return string
     end
 
-    ## Restores a +string+ whose ending may have been glued.
+    # Restores a +string+ whose ending may have been glued.
     def unglue_back(string)
         if string.end_with?(@glue) then
             # There is a glue, so remove it.
@@ -491,8 +501,7 @@ class Preprocessor
         return string
     end
 
-    ## Gest the range of an argument starting
-    #  from offset +start+ of +line+.
+    # Gets the range of an argument starting at offset +start+ in +line+.
     def get_argument_range(line, start)
         if start >= line.size then
             raise "incomplete arguments in macro call."
@@ -501,8 +510,9 @@ class Preprocessor
         return (range[0]+start)..(range[1]+start-1)
     end
 
-    ## Iterates over the range each argument of a +line+ from offset +start+.
-    #  NOTE: keywords included into a longer one are ignored.
+    # Iterates over the range each argument of a +line+ from offset +start+.
+    #
+    # NOTE: keywords included into a longer one are ignored.
     def each_argument_range(line,start)
         return to_enum(:each_argument_range,line,start) unless block_given?
         begin
@@ -519,22 +529,22 @@ class Preprocessor
     end
 
 
-    ## Tells if a line corresponds to an end keyword.
+    # Tells if a line corresponds to an end keyword.
     def is_endm?(line)
         @endm.match(line)
     end
 
-    ## Tells if a line corresponds to an else keyword.
+    # Tells if a line corresponds to an else keyword.
     def is_elsem?(line)
         @elsem.match(line)
     end
 
-    ## Tells if a line corresponds to an endif keyword.
+    # Tells if a line corresponds to an endif keyword.
     def is_endifm?(line)
         @endifm.match(line)
     end
 
-    ## Extract a macro definition from a +line+ if there is one.
+    # Extract a macro definition from a +line+ if there is one.
     def get_macro_def(line)
         line = line.strip
         # Locate and identify the macro keyword.
@@ -613,9 +623,9 @@ class Preprocessor
     end
 
 
-    ## Apply recursively each element of +macros+ to +line+.
+    # Applies recursively each element of +macros+ to +line+.
     #
-    #  NOTE: a same macro is apply only once in a portion of the line.
+    # NOTE: a same macro is apply only once in a portion of the line.
     def apply_macros(line)
         # print "apply_macros on line=#{line}\n"
 
@@ -677,10 +687,10 @@ class Preprocessor
         return expanded
     end
 
-    ## Close a +macro+ being input registering it if named or applying it
-    #  otherwise.
+    # Close a +macro+ being input registering it if named or applying it
+    # otherwise.
     #  
-    #  NOTE: for internal use only.
+    # NOTE: for internal use only.
     def close_macro(macro)
         # Is the macro named?
         unless macro.name.empty? or macro.is_a?(Assign) then
@@ -717,8 +727,8 @@ class Preprocessor
     end
     private :close_macro
 
-    ## Preprocess an +input+ stream and write the result to an +output+
-    #  stream.
+    # Preprocess an +input+ stream and write the result to an +output+
+    # stream.
     def preprocess(input, output)
         # # The current list of macros.
         # @macros = KeywordSearcher.new(@separator)

data/lib/ppr/safer_generator.rb

@@ -5,24 +5,24 @@
 ######################################################################
 
 
-## Class which allows to safely execute a proc which generate safely
-#  a string into a stream.
+# Tool for executing in a safer sandbox a proc that generates a string into a
+# stream.
 class SaferGenerator
 
-    ## The exception raised when the safer processed failed.
+    # The exception raised when the safer processed failed.
     class SaferException < RuntimeError
     end
 
-    ## The list of dangerous constants of Object.
+    # The list of dangerous constants of Object.
     DANGER_CONSTANTS = [ :File, :IO, :Dir ]
 
-    ## The list of dangerous methods of Kernel
+    # The list of dangerous methods of Kernel
     DANGER_METHODS  = [ :system, :`, :open ]
 
 
-    ## Creates a new safe context with while removing Kernel methods and
-    #  constants from +black_list+ in addition to the default dangerous
-    #  ones.
+    # Creates a new safe context with while removing Kernel methods and
+    # constants from +black_list+ in addition to the default dangerous
+    # ones.
     def initialize(*black_list)
         # Set the black list of methods.
         @black_methods = black_list.select do |symbol|
@@ -34,10 +34,10 @@ class SaferGenerator
         end
     end
 
-    ## Strips all the Kernel methods and constants appart from the
-    #  elements of the white list.
-    #  Also strip Object from dangerous methods and constants apart
-    #  from the elements of the white list.
+    # Strips all the Kernel methods and constants appart from the
+    # elements of the white list.
+    # Also strip Object from dangerous methods and constants apart
+    # from the elements of the white list.
     def secure
         # Gather the methods to strip.
         methods = DANGER_METHODS + @black_methods
@@ -54,9 +54,9 @@ class SaferGenerator
     end
 
 
-    ## Executes +block+ in a safe context for  generating text into a +stream+.
+    # Executes +block+ in a safe context for  generating text into a +stream+.
     #
-    #  If no stream is given, returns the result as a string instead.
+    # If no stream is given, returns the result as a string instead.
     def run(stream = nil, &block)
         unless stream
             # No stream given

data/lib/ppr/version.rb

@@ -1,3 +1,3 @@
 module Ppr
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/ppr.rb

@@ -1,9 +1,10 @@
 require "ppr/version"
 require "ppr/ppr_core"
 
-## Module including the classes implementing the preprocessor in Ruby.
+##
+# Module including the classes implementing the preprocessor in Ruby.
 #
-#  Usage:
+# Usage:
 #    ppr = Ppr::Preprocessor.new(<some options>) 
 #    ppr.preprocess(<input stream to preprocess>,
 #                   <output stream where to write the preprocessing result>)}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ppr
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Lovic Gauthier