-- -*- Mode: rpl; -*-                                                                               
--
-- prelude.rpl
--
-- © Copyright IBM Corporation 2018.
-- LICENSE: MIT License (https://opensource.org/licenses/mit-license.html)
-- AUTHOR: Jamie A. Jennings

-- This package is in the rpl/builtin directory.  When a builtin package is imported, the
-- bindings do NOT originate from compiling this file.  Instead, the bindings are constructed
-- internally by the Rosie code.  This file exists for documentation purposes.

rpl 1.1
package prelude

-- Patterns

alias $ = $				-- end of input
alias . = .				-- see below
alias ^ = ^				-- start of input
alias ~ = ~				-- see below

-- Macros and functions for case sensitivity

ci = ci					-- case-insensitive version of arg

-- Macros and functions for searching

find = find				-- skip ahead until arg matches
findall = findall			-- find all matches of arg
keepto = keepto				-- capture all until arg matches

message = message			-- inserts message node into match
error = error				-- inserts error node into match, then aborts


-- Notes on dot and boundary:
-- 
-- .
-- Dot is defined to match one Unicode character encoded in UTF-8, or, failing that, a single byte.
--
-- ~
-- The boundary symbol, tilde, is defined to match any of these (in order):
--   [:space:]+                   consume all whitespace
--   { >word_char !<word_char }   looking at a word char, and back at non-word char
--   >[:punct:] / <[:punct:]      looking at punctuation, or back at punctuation
--   { <[:space:] ![:space:] }    looking back at space, but not ahead at space
--   $                            looking at end of input
--   ^                            looking back at start of input
-- 
-- where word_char is the ASCII-only pattern [[A-Z][a-z][0-9]]


-- Notes on macros for case sensitivity:
--
-- The ci macro takes a literal string argument and constructs a pattern that returns a
-- case-insensitive pattern for matching that string.  For example:
-- $ bin/rosie match -o subs 'find:ci:"IBM"' test/resolv.conf
-- ibm


-- Notes on macros for searching:
--
-- The macros find, findall, and keepto take a pattern argument, which can be any pattern.
--   find:p        finds the first occurrence of p and matches it
--   findall:p     finds all occurrences of p and matches them
--   keepto:p      capture everything up to and including the first occurrence of p
-- 
-- Examples                                                                Notes
--
-- $ bin/rosie match 'find:date.any' test/resolv.conf
-- # Last update: Wed Jun 28 16:58:22 EDT 2017                             # Wed Jun 28 in blue
-- nameserver 192.9.201.1                                                  # 2.9.20 in blue
-- nameserver 192.9.201.2                                                  # 2.9.20 in blue
-- $ bin/rosie match -o subs 'find:date.any' test/resolv.conf
-- Wed Jun 28 
-- 2.9.20
-- 2.9.20
-- $ bin/rosie match -o subs 'find:(date.any)' test/resolv.conf
--  Wed Jun 28 
-- $ bin/rosie match '"search" find:net.fqdn_strict' test/resolv.conf
-- search ibm.com mylocaldomain.myisp.net example.com
-- $ bin/rosie -o subs match '"search" find:net.fqdn_strict' test/resolv.conf
-- ibm.com
-- $ bin/rosie -o subs match '"search" findall:net.fqdn_strict' test/resolv.conf
-- ibm.com
-- mylocaldomain.myisp.net
-- example.com
-- $ bin/rosie match find:ts.any test/resolv.conf                # full match includes chars before ts.any
-- # Last update: Wed Jun 28 16:58:22 EDT 2017
-- $ bin/rosie match -o subs find:ts.any test/resolv.conf        # sub-match is result of 'find'
-- Wed Jun 28 16:58:22 EDT 2017
-- $ bin/rosie match -o subs keepto:ts.any test/resolv.conf      # two subs: chars before ts.any, and ts.any
-- # Last update: 
-- Wed Jun 28 16:58:22 EDT 2017
-- $
