srl_ruby 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1ac4b0f8fd97b06c70f416ef86a1be451e66c120
-  data.tar.gz: 57c2baed9fc6659842ca4b0df87686a5ce1fdb38
+  metadata.gz: aec2fc57a4a6eadb94d63cbb5b3edaaab988ceff
+  data.tar.gz: fb2a6b4007134fd657c749e9979610e562b13ff3
 SHA512:
-  metadata.gz: 73b82f0ab75ed3a0426809ec69c00448f1212efbc4d4216a9293094080d9ec734421ebb62868c4b84858aef7408d75ab69fd61567d10f004f64b981383b4eddc
-  data.tar.gz: de79ea767f4a30d454f1b266c5581796a9881e83e6452fbf7398d3f99cb938b5b1a3fd17b6804ef89af6c8f6e116df4a41a990cc9ab7606780489198bb645ab5
+  metadata.gz: 2319c820f448ffffc89ed753f39c724fa7c438ebaa5930b5ee2aa9c303f7dedd3f23523a865ddf1a13838ec70e2f10a717cce1c562b4f98f61050a99d77d1437
+  data.tar.gz: d975c484f19792cae40c23fbfc6294f606ffe49cff29ecf07519447585cf80e332e10e7ec1422846f501ae14dec2f8773c1fe0e04905ea9177214b60193a24ab

data/CHANGELOG.md

@@ -6,6 +6,13 @@
 ### Fixed
 ### Security
 
+## [0.1.0] - 2018-03-08
+### Added
+- Version bump. Added new API methods `SrlRuby#load_file` and `SrlRuby#parse`
+
+### Changed
+- File `README.md` vastly improved with examples and usage snippet.
+
 ## [0.0.2] - 2018-03-07
 ### Added
 - File `CHANGELOG.md`. This file. Adopting `keepachangelog.com` recommended format.

data/README.md

@@ -8,33 +8,97 @@
 This project implements a [Simple Regex Language](https://simple-regex.com) parser and interpreter in Ruby.
 
 ## What is SRL?
-SRL is a small language lets you write regular expressions
-with a readable syntax that bears some resemblance with English.
-Here are a couple of hyperlinks of interest:  
-[Main SRL website](https://simple-regex.com)  
-[SRL libraries](https://github.com/SimpleRegex)
+[SRL](https://github.com/SimpleRegex) is a small language that lets you write pattern matching expressions
+in a readable syntax that bears some resemblance with English.
 
+As an example, let's assume that our mission is to create a regular expression
+that matches the time in 12 hour clock format.  
+Here is a SRL expression that matches the _hh:mm AM/PM_ time format:
+```
+digit from 0 to 1,
+digit optional,
+literally ":",
+digit from 0 to 5, digit,
+literally " ",
+one of "AP", literally "M"
+```
 
-## An example
-Let's assume that we want to create a regular expression that recognizes time in a day in the 24 hours format hh:mm:ss.
-In SRL:
+## Why SRL?
+Even without knowing SRL, a reader can easily grasp the details of the above SRL expression.
+This is where SRL shines over the traditional regular expressions: high readability.
+For instance, a regex for the clock format problem may look like this:
 ```
-digit from 0 to 2, digit,
-(literally ':', digit from 0 to 5, digit) twice
+/[0-1]?\d:[0-5]\d [AP]M/
 ```
 
-If one runs the `srl_ruby` command-line like this:
+In terms of terseness, regexes are hard to beat. But it is also a well-known fact: regexes can be really hard to write and even harder to read ('decipher' verb is closer to reality).  
+Alas, the path of creating and maintaining regexes can be full of frustration.
 
+There comes SRL. The intent is to let developers define self-documenting patterns with an easy syntax.
+And then let your computer translate SRL expressions into regular expressions.
+`srl_ruby` allows you to craft self-documenting patterns in SRL and then generate
+their Ruby regular expression representation.
+
+
+Ah, by the way, our clock format pattern isn't completely correct. It will match invalid times like 19:34 PM.
+The problem arises when the first digit in the hour field is a one: in that case the second digit can only be
+zero or one.
+
+Let's fix the issue in SRL:
 ```
-srl_ruby "digit from 0 to 2, digit, (literally ':', digit from 0 to 5, digit) twice"
-```
-It replies with:
+any of (
+  (literally "0" optional, digit),
+  (literally "1", one of "01")
+),
+literally ":",
+digit from 0 to 5, digit,
+literally " ",
+one of "AP", literally "M"
 ```
-SRL input: digit from 0 to 2, digit, (literally ':', digit from 0 to 5, digit) twice
-Resulting Regexp: /[0-2]\d(?::[0-5]\d){2}/
+
+And there is the equivalent regex found by `srl_ruby`:  
+/(?:(?:0?\d)|(?:1[01])):[0-5]\d [AP]M/
+
+### More about Simple Regex Language syntax and examples
+    Here are a couple of hyperlinks of interest:  
+    [Main SRL website](https://simple-regex.com)  
+    [SRL libraries](https://github.com/SimpleRegex)
+
+
+## Usage
+The following snippet...  
+
+```ruby
+require 'srl_ruby' # Load srl_ruby library
+
+
+# Here is a multiline SRL expression that matches dates
+# in yyyy-mm-dd format
+some_srl = <<-END_SRL
+  any of (literally "19", literally "20"), digit twice,
+  literally "-",
+  any of (
+    (literally "0", digit),
+    (literally "1", one of "012")
+  ),
+  literally "-",
+  any of (
+    (literally "0", digit),
+    (one of "12", digit),
+    (literally "3", one of "01")
+  )  
+END_SRL
+
+# Next line launches the SRL parser, it returns the corresponding regex literal
+result = SrlRuby.parse(some_srl)
+
+puts 'Equivalent regexp: /' + result + '/'
 ```
 
-In other words, it translates a readable SRL expression into its regexp equivalent.
+...  produces the following output:
+```
+Equivalent regexp: /(?:19|20)\d{2}-(?:(?:0\d)|(?:1[012]))-(?:(?:0\d)|(?:[12]\d)|(?:3[01]))/
+```
 
 ## Installation
 

data/bin/srl_ruby

@@ -1,12 +1,6 @@
 #!/usr/bin/env ruby
-require_relative '../lib/srl_ruby/tokenizer'
-require_relative '../lib/srl_ruby/grammar'
-require_relative '../lib/srl_ruby/ast_builder'
+require_relative '../lib/srl_ruby/srl_ruby'
 
-def print_title(aTitle)
-  puts aTitle
-  puts '=' * aTitle.size
-end
 
 # Parse the input expression in command-line
 if ARGV.empty?
@@ -29,30 +23,6 @@ END_MSG
   exit(1)
 end
 puts 'SRL input: ' + ARGV[0]
-
-# Create a Rley facade object
-engine = Rley::Engine.new
-
-########################################
-# Step 1. Load a grammar for calculator
-engine.use_grammar(SrlRuby::Grammar)
-
-lexer = SrlRuby::Tokenizer.new(ARGV[0])
-result = engine.parse(lexer.tokens)
-
-unless result.success?
-  # Stop if the parse failed...
-  puts "Parsing of '#{ARGV[0]}' failed"
-  puts "Reason: #{result.failure_reason.message}"
-  exit(1)
-end
-
-# Generate an abstract syntax tree (AST) from the parse result
-engine.configuration.repr_builder = SrlRuby::ASTBuilder
-ast_ptree = engine.convert(result)
-
-# Now output the regexp literal
-root = ast_ptree.root
-puts "Resulting Regexp: /#{root.to_str}/" # Output the expression result
+puts 'Resulting Regexp: /' + SrlRuby.parse(ARGV[0]) + '/'
 
 # End of file

data/lib/srl_ruby/version.rb

@@ -1,3 +1,3 @@
 module SrlRuby
-  VERSION = '0.0.2'.freeze
+  VERSION = '0.1.0'.freeze
 end

data/lib/srl_ruby.rb

@@ -1,4 +1,46 @@
 require_relative './srl_ruby/version'
+require_relative './srl_ruby/tokenizer'
+require_relative './srl_ruby/grammar'
+require_relative './srl_ruby/ast_builder'
 
 module SrlRuby # This module is used as a namespace
-end
+  # Load the SRL expression contained in filename. 
+  # Returns the literal regular expression representation 
+  # as a Ruby String.
+  # @param filename [String] file name to parse.
+  def self.load_file(filename)
+    source = nil
+    File.open(filename, 'r') { |f| source = f.read }
+    return source if source.nil? || source.empty?
+    
+    return parse(source)
+  end
+  
+  # Parse the SRL expression into its literal regexp and return it.
+  # @param source [String] the SRL source to parse and convert.
+  def self.parse(source)
+    # Create a Rley facade object
+    engine = Rley::Engine.new
+
+    # Step 1. Load SRL grammar
+    engine.use_grammar(SrlRuby::Grammar)
+
+    lexer = SrlRuby::Tokenizer.new(source)
+    result = engine.parse(lexer.tokens)
+
+    unless result.success?
+      # Stop if the parse failed...
+      line1 = "Parsing of '#{source}' failed\n"
+      line2 = "Reason: #{result.failure_reason.message}"
+      raise StandardError, line1 + line2
+    end
+
+    # Generate an abstract syntax tree (AST) from the parse result
+    engine.configuration.repr_builder = SrlRuby::ASTBuilder
+    ast_ptree = engine.convert(result)
+
+    # Now output the regexp literal
+    root = ast_ptree.root
+    return root.to_str
+  end
+end # module

data/srl_ruby.gemspec

@@ -26,7 +26,7 @@ module PkgExtending
   end
 
   def self.pkg_documentation(aPackage)
-    aPackage.rdoc_options << '--charset=UTF-8 --exclude="examples|features|spec"'
+    aPackage.rdoc_options << '--charset=UTF-8 --exclude="examples|spec"'
     aPackage.extra_rdoc_files = ['README.md']
   end
 end # module
@@ -37,10 +37,11 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Dimitri Geshef']
   spec.email         = ['famished.tiger@yahoo.com']
 
-  spec.summary       = %q(A parser for the Simple Regex Language, written in Ruby.)
-  spec.description   = <<-END_DESCR
-srl_ruby is a Ruby gem implementing a parser for Simple Regex Language (SRL).
-It reads then converts SRL input into Ruby Strings or Regexp. 
+  spec.description   = %q(A parser for the Simple Regex Language (SRL).)
+  spec.summary   = <<-END_DESCR
+srl_ruby is a gem implementing a parser for Simple Regex Language (SRL).
+It translates patterns expressed in SRL into plain Ruby Regexp objects 
+or regex literals. 
 END_DESCR
   spec.homepage      = 'https://github.com/famished-tiger/SRL-Ruby'
   spec.license       = 'MIT'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: srl_ruby
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Dimitri Geshef
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-03-07 00:00:00.000000000 Z
+date: 2018-03-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rley
@@ -66,8 +66,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description: "srl_ruby is a Ruby gem implementing a parser for Simple Regex Language
-  (SRL).\nIt reads then converts SRL input into Ruby Strings or Regexp. \n"
+description: A parser for the Simple Regex Language (SRL).
 email:
 - famished.tiger@yahoo.com
 executables:
@@ -126,7 +125,7 @@ licenses:
 metadata: {}
 post_install_message: 
 rdoc_options:
-- --charset=UTF-8 --exclude="examples|features|spec"
+- --charset=UTF-8 --exclude="examples|spec"
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
@@ -144,7 +143,9 @@ rubyforge_project:
 rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
-summary: A parser for the Simple Regex Language, written in Ruby.
+summary: srl_ruby is a gem implementing a parser for Simple Regex Language (SRL).
+  It translates patterns expressed in SRL into plain Ruby Regexp objects  or regex
+  literals.
 test_files:
 - spec/integration_spec.rb
 - spec/regex/character_spec.rb