fop_lang 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7cfe0a53d59b00d2fc60f0c0f5ed3e413eb61cf0ae445d49562f0cf861cd9f0b
-  data.tar.gz: 5aa04d8145417d52b42847be17b54a230242143486278d2826adacb7d1143101
+  metadata.gz: 798fd7c335f394e878fba2f70a9f60372ea356c79f2dc63392398920d0ffce38
+  data.tar.gz: 654786ff77823e8d8dd9a348f958828346e3755e43a04a0f38e711a6c5571ea9
 SHA512:
-  metadata.gz: 79efdf103e6e33bc508df356e2295ac49c8f112ad44a0c3aad4209bb204fadcd240b12f14f62ee3266d21762afec1e8a3262b767fda42cc7ebf019688bfbe30e
-  data.tar.gz: 1f424bf43332438a3f223af0737fa6570de8e06444669edd8808e5d41e2804fe9139598f58336ca098a1b67fba8741519375e3700916747acb8df6ddace3294d
+  metadata.gz: 6761f3d7dd602d1c93a2387fc73ea14c11484e88d0d319bbf87df98925977aa15de59a63f23aafffafa384ce3b9def9f81edabae669aabc2012b00d3131e46f4
+  data.tar.gz: 7f5187cd510d691dda996284d5a400804b7573f67506701e39a6d2909c8a4026b58655f6b2800708e911377ccce790885a2238eed7a75d4873e4b599d23e67df

data/README.md

@@ -1,57 +1,99 @@
 # fop_lang
 
-Fop (Filter and OPerations language) is an experimental, tiny expression language in the vein of awk and sed. This is a Ruby implementation. It is useful for simultaneously matching and transforming text input.
+Fop (Filter and OPerations language) is a tiny, experimental language for filtering and transforming text. Think of it like awk but with the condition and action segments combined.
 
-```ruby
-gem 'fop_lang'
-```
+This is a Ruby implementation with both a library interface and a bin command.
 
-## Release Number Example
+## Installation
 
-This example takes in GitHub branch names, decides if they're release branches, and if so, increments the version number.
+```bash
+$ gem install fop_lang
+```
+
+You may use fop in a Ruby script:
 
 ```ruby
-  f = Fop('release-{N}.{N+1}.{N=0}')
+require 'fop_lang'
 
-  puts f.apply('release-5.99.1')
-  =>           'release-5.100.0'
+f = Fop('foo {N+1}')
 
-  puts f.apply('release-5')
-  => nil
-  # doesn't match the pattern
+f.apply('foo 1')
+=> "foo 2"
+
+f.apply('bar 1')
+=> nil
+```
+
+or run `fop` from the command line:
+
+```bash
+$ echo 'foo 1' | fop 'foo {N+1}'
+foo 2
+$ echo 'bar 1' | fop 'foo {N+1}'
 ```
 
-## Anatomy of a Fop expression
+## Syntax
+
+`Text /(R|r)egex/ {N+1}`
+
+The above program demonstrates a text match, a regex match, and a match expression. If the input matches all three segments, output is given. If the input was `Text regex 5`, the output would be `Text regex 6`.
+
+### Text match
+
+The input must match this text exactly. Whitespace is part of the match. Wildcards (`*`) are allowed. Special characters (`*/{}\`) may be escaped with `\`.
 
-`Text Literal {Operation}`
+The output of a text match will be the matching input.
 
-The above expression contains the only two parts of Fop (except for the wildcard and escape characters).
+### Regex match
 
-**Text Literals**
+Regular expressions may be placed between `/`s. If the regular expression contains a `/`, you may escape it with `\`. Special regex characters like `[]()+.*` may also be escaped with `\`.
 
-A text literal works how it sounds: the input must match it exactly. If it matches it passes through unchanged. The only exception is the `*` (wildcard) character, which matches 0 or more of anything. Wildcards can be used anywhere except inside `{...}` (operations).
+The output of a regex match will be the matching input.
 
-If `\` (escape) is used before the special characters `*`, `{` or `}`, then that character is treated like a text literal. It's recommended to use single-quoted Ruby strings with Fop expressions that so you don't need to double-escape.
+### Match expression
 
-**Operations**
+A match expression both matches on input and modifies that input. An expression is made up of 1 - 3 parts:
 
-Operations are the interesting part of Fop, and are specified between `{` and `}`. An Operation can consist of one to three parts:
+1. The match, e.g. `N` for numeric.
+2. The operator, e.g. `+` for addition (optional).
+3. The argument, e.g `1` for "add one" (required for most operators).
 
-1. Matching class (required): Defines what characters the operation will match and operate on.
-  * `N` is the numeric class and will match one or more digits.
-  * `A` is the alpha class and will match one or more letters (lower or upper case).
-  * `W` is the word class and matches alphanumeric chars and underscores.
-  * `*` is the wildcard class and greedily matches everything after it.
-  * `/.../` matches on the supplied regex between the `/`'s. If you're regex contains a `/`, it must be escaped. Capture groups may be referenced in the operator argument as `$1`, `$2`, etc.
-3. Operator (optional): What to do to the matching characters.
-  * `=` Replace the matching character(s) with the given argument. If no argument is given, drop the matching chars.
-  * `>` Append the following chars to the matching value.
-  * `<` Prepend the following chars to the matching value.
-  * `+` Perform addition on the matching number and the argument (`N` only).
-  * `-` Subtract the argument from the matching number (`N` only).
-5. Operator argument (required for some operators): meaning varies by operator.
+The output of a match expression will be the _modified_ matching input. If no operator is given, the output will be the matching input.
+
+**Matches**
+
+* `N` matches one or more consecutive digits.
+* `A` matches one or more letters (lower or upper case).
+* `W` matches alphanumeric chars and underscores.
+* `*` greedily matches everything after it.
+* `/regex/` matches on the supplied regex. Capture groups may be referenced in the argument as `$1`, `$2`, etc.
+
+**Operators**
+
+* `=` Replace the matching character(s) with the given argument. If no argument is given, drop the matching chars.
+* `>` Append the argument to the matching value.
+* `<` Prepend the argument to the matching value.
+* `+` Perform addition on the matching number and the argument (`N` only).
+* `-` Subtract the argument from the matching number (`N` only).
+
+## Examples
+
+### Release Number Example
+
+This example takes in GitHub branch names, decides if they're release branches, and if so, increments the version number.
+
+```ruby
+  f = Fop('release-{N}.{N+1}.{N=0}')
+
+  puts f.apply('release-5.99.1')
+  =>           'release-5.100.0'
+
+  puts f.apply('release-5')
+  => nil
+  # doesn't match the pattern
+```
 
-## More Examples
+### More Examples
 
 ```ruby
   f = Fop('release-{N=5}.{N+1}.{N=0}')

data/bin/fop

@@ -7,7 +7,18 @@ require 'fop_lang'
 require 'fop/cli'
 
 opts = Fop::CLI.options!
+
+if opts.version
+  puts Fop::VERSION
+  exit 0
+end
+
 src = opts.src.read.chomp
+if src.empty?
+  $stderr.puts "No expression given"
+  exit 1
+end
+
 fop, errors = Fop.compile(src)
 opts.src.close
 NL = "\n".freeze

data/lib/fop/cli.rb

@@ -2,7 +2,7 @@ require 'optparse'
 
 module Fop
   module CLI
-    Options = Struct.new(:src, :check, :quiet)
+    Options = Struct.new(:src, :check, :quiet, :version)
 
     def self.options!
       options = Options.new
@@ -18,12 +18,16 @@ module Fop
           options.check = true
         end
 
-        opts.on("-q", "--quiet") do
+        opts.on("-q", "--quiet", "Only print errors and output") do
           options.quiet = true
         end
+
+        opts.on("--version", "Print version and exit") do
+          options.version = true
+        end
       end.parse!
 
-      options.src ||= StringIO.new(ARGV.shift)
+      options.src ||= StringIO.new(ARGV.shift || "")
       options
     end
   end

data/lib/fop/version.rb

@@ -1,3 +1,3 @@
 module Fop
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fop_lang
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Jordan Hollinger
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-08-20 00:00:00.000000000 Z
+date: 2021-08-30 00:00:00.000000000 Z
 dependencies: []
 description: A micro expression language for Filter and OPerations on text
 email: jordan.hollinger@gmail.com