docs: update docstrings and readme

README.md

@@ -4,7 +4,7 @@ All-in-one coupler for [COSIPY](https://cosipy.readthedocs.io) and WRF.
 
 ## Pre-requisites
 
-1. Install patcher dependencies
+1. Install patcher dependencies.
 
 Perl version 5.26.3 or greater must be installed on your system. Depending on your distribution, you may also need to install the following:
 
@@ -47,7 +47,63 @@ Depending on your system and access permissions, you may need to run ``build_wrf
 --install-coupler   Install only the coupler code.
 --wrf-branch <str>  Name of WRF branch on GitHub. Defaults to 'release-v4.6.1'.
 -c, --configure     Create new WRF configuration script.
--p, --patch         Patch COSIPY into WRF. Does not check if already patched!
+-p, --patch         Patch COSIPY into WRF.
 -e, --env           Load environment variables.
 -v, --verbose       Prints log messages to stderr.
 ```
+
+## Adding Patches
+
+You can also view this documentation by running ``perldoc backend_patcher.pl``.
+
+Patching a file in ``backend_patcher.pl`` always follows the same template.
+Note that brackets in the string being matched must be escaped with ``\\``.
+
+```perl
+my $input_file = "${input_dir}path/to/file";
+$check_file = get_file_is_safe($input_file); # file exists and isn't patched
+if ($check_file) {
+    copy_file($input_file); # backup original file
+    $string_match = "happy birthday"; # whitespace-sensitive
+    $label        = set_patch_label();  # if you want to include a signature
+    $whitespace = " " x 5 # if you want to include whitespace
+    # patch method goes here
+}
+```
+
+### Add a line
+
+You can add individual lines by hardcoding the script:
+
+```perl
+$string_match = "happy birthday"; # whitespace-sensitive
+$string_new = "${label}${whitespace}to you!\nhappy birthday";
+add_line_to_file( $input_file, $string_match, $string_new, "p" );
+```
+``add_line_to_file`` takes three modes: "p" (prepend), "a" (append), "r" (replace).
+
+### Add from patch file
+
+For more complex patching, add a file with an identical name to the one you wish to patch under ``./patch_files``.
+Separate hunks using ``===N===``, where N is an index.
+
+```
+===1===
+some string
+and another
+===1===
+===2===
+a second paragraph
+    with whitespace
+===2===
+```
+
+Use the index number to refer directly to the hunk you wish to add:
+
+```perl
+$patch_file = "${patch_dir}file";
+$string_match = "some string"; # whitespace-sensitive
+patch_from_file_array( $input_file, $patch_file, $string_match, 1, "a" );
+```
+
+``patch_from_file_array`` takes three modes: "p" (prepend), "a" (append), "r" (replace).

src/patch_wrfxcspy/README.md

@@ -4,7 +4,7 @@ All-in-one coupler for [COSIPY](https://cosipy.readthedocs.io) and WRF.
 
 ## Pre-requisites
 
-1. Install patcher dependencies
+1. Install patcher dependencies.
 
 Perl version 5.26.3 or greater must be installed on your system. Depending on your distribution, you may also need to install the following:
 
@@ -47,7 +47,63 @@ Depending on your system and access permissions, you may need to run ``build_wrf
 --install-coupler   Install only the coupler code.
 --wrf-branch <str>  Name of WRF branch on GitHub. Defaults to 'release-v4.6.1'.
 -c, --configure     Create new WRF configuration script.
--p, --patch         Patch COSIPY into WRF. Does not check if already patched!
+-p, --patch         Patch COSIPY into WRF.
 -e, --env           Load environment variables.
 -v, --verbose       Prints log messages to stderr.
 ```
+
+## Adding Patches
+
+You can also view this documentation by running ``perldoc backend_patcher.pl``.
+
+Patching a file in ``backend_patcher.pl`` always follows the same template.
+Note that brackets in the string being matched must be escaped with ``\\``.
+
+```perl
+my $input_file = "${input_dir}path/to/file";
+$check_file = get_file_is_safe($input_file); # file exists and isn't patched
+if ($check_file) {
+    copy_file($input_file); # backup original file
+    $string_match = "happy birthday"; # whitespace-sensitive
+    $label        = set_patch_label();  # if you want to include a signature
+    $whitespace = " " x 5 # if you want to include whitespace
+    # patch method goes here
+}
+```
+
+### Add a line
+
+You can add individual lines by hardcoding the script:
+
+```perl
+$string_match = "happy birthday"; # whitespace-sensitive
+$string_new = "${label}${whitespace}to you!\nhappy birthday";
+add_line_to_file( $input_file, $string_match, $string_new, "p" );
+```
+``add_line_to_file`` takes three modes: "p" (prepend), "a" (append), "r" (replace).
+
+### Add from patch file
+
+For more complex patching, add a file with an identical name to the one you wish to patch under ``./patch_files``.
+Separate hunks using ``===N===``, where N is an index.
+
+```
+===1===
+some string
+and another
+===1===
+===2===
+a second paragraph
+    with whitespace
+===2===
+```
+
+Use the index number to refer directly to the hunk you wish to add:
+
+```perl
+$patch_file = "${patch_dir}file";
+$string_match = "some string"; # whitespace-sensitive
+patch_from_file_array( $input_file, $patch_file, $string_match, 1, "a" );
+```
+
+``patch_from_file_array`` takes three modes: "p" (prepend), "a" (append), "r" (replace).

src/patch_wrfxcspy/backend_patcher.pl

@@ -38,7 +38,7 @@ sub set_patch_label {
     my $label = "${prefix}WRF_X_CSPY";
     if ( $year == 1 ) {
         $year  = get_year();
-        $label = "${label} EC${year}\n";
+        $label = "${label} ${year}\n";
     }
     else {
         $label = "${label}\n";
@@ -57,12 +57,52 @@ sub set_label_wrap {
 
 }
 
+=head2 I<File Handling>
+
+=over
+
+=item get_file_is_safe($input_file, $patch_label)
+
+Check if a file exists and has been patched.
+
+Parameters:
+
+=over
+
+=item path to file
+
+=item patch label. If this is found anywhere in the file, it is considered patched.
+
+=back
+
+=item get_file_exists($input_file)
+
+Check a file exists.
+
+=item get_file_is_patched($input_file, $patch_label)
+
+Check if a file has been patched.
+
+Parameters:
+
+=over
+
+=item path to file
+
+=item patch label. If this is found anywhere in the file, it is considered patched.
+
+=back
+
+=back
+
+=cut
+
 sub get_file_is_safe {
-    my ( $input_file, $label ) = @_;
-    $label ||= "\\!WRF_X_CSPY";
+    my ( $input_file, $patch_label ) = @_;
+    $patch_label ||= "\\!WRF_X_CSPY";
     my $file_exists = get_file_exists($input_file);
     if ($file_exists) {
-        my $file_patched = get_file_is_patched( $input_file, $label );
+        my $file_patched = get_file_is_patched( $input_file, $patch_label );
         if ($file_patched) {
             return 1;
         }
@@ -115,11 +155,15 @@ =head2 I<Regex Functions>
 
 =item regex_prepend_to_line($match_string, $new_text)
 
-Prepends missing text before matching string.
+Prepends new text before matching string.
 
 =item regex_append_to_line($match_string, $new_text)
 
-Appends missing text after matching string.
+Appends new text after matching string.
+
+=item regex_replace_line($match_string, $new_text)
+
+Replaces matching string with new text.
 
 =back
 
@@ -175,15 +219,16 @@ =head2 I<File Editing>
 
 =item string to match
 
-=item missing text
+=item new text
 
-=item edit mode: 'p' -> prepend, 'a' -> append, 'n' -> prepend by n lines.
+=item edit mode: 'p' -> prepend, 'a' -> append, 'r' -> replace line.
 
 =back
 
-=item patch_from_file($file_path, $patch_path, $match_string, $mode)
+=item patch_from_file_array($file_path, $patch_path, $match_string, $mode)
 
 Patches text from another file.
+Hunks in the patch file must be separated with "===N===", where N is an index.
 
 Parameters:
 
@@ -195,7 +240,7 @@ =head2 I<File Editing>
 
 =item string to match
 
-=item edit mode: 'p' -> prepend, 'a' -> append, 'n' -> prepend by n lines.
+=item edit mode: 'p' -> prepend, 'a' -> append, 'r' -> replace line.
 
 =back
 
@@ -210,9 +255,6 @@ sub add_line_to_file {
         if ( $mode eq "p" ) {
             regex_prepend_to_line( $match_string, $new_text );
         }
-        elsif ( $mode eq "n" ) {
-            regex_prepend_to_line_number( $match_string, $new_text );
-        }
         elsif ( $mode eq "a" ) {
             regex_append_to_line( $match_string, $new_text );
         }
@@ -229,30 +271,6 @@ sub add_line_to_file {
     close $out;
 }
 
-sub patch_from_file {
-    my ( $file_path, $patch_path, $match_string, $mode ) = @_;
-    my ( $in, $out ) = open_file($file_path);
-    my $patch_text = path($patch_path)->slurp;
-    $patch_text = set_label_wrap( $patch_text, "#" );
-    while (<$in>) {
-        if ( $mode eq "p" ) {
-            regex_prepend_to_line( $match_string, $patch_text );
-        }
-        elsif ( $mode eq "a" ) {
-            regex_append_to_line( $match_string, $patch_text );
-        }
-        else {
-            die "Mode $! not supported.";
-        }
-
-        print $out $_;
-    }
-
-    # }
-    close $out;
-    close $patch_text;
-}
-
 sub patch_from_file_array {
 
     # hunks are separated by ===N=== in the corresponding patch file.
@@ -270,6 +288,9 @@ sub patch_from_file_array {
         elsif ( $mode eq "a" ) {
             regex_append_to_line( $match_string, $patch_text );
         }
+        elsif ( $mode eq "r" ) {
+            regex_replace_line( $match_string, $new_text );
+        }
         else {
             die "Mode $! not supported.";
         }
@@ -292,7 +313,7 @@ sub patch_from_file_array {
 # path to a patch file.
 
 # You can add individual lines to a file.
-# Use "a" for append or "p" for prepend.
+# Use "a" for append, "p" for prepend, or "r" to replace.
 
 # my $file  = "${input_dir}foo/bar";
 # my $string_match = "happy birthday";
@@ -301,7 +322,7 @@ sub patch_from_file_array {
 
 # You can patch hunks from files in the patch_files directory.
 # Hunks must be separated with "===N===", where N is an index.
-# Use "a" for append or "p" for prepend.
+# Use "a" for append, "p" for prepend, or "r" to replace.
 
 # my $file  = "${input_dir}foo/bar";
 # my $patch_file = "${patch_dir}bar";

src/patch_wrfxcspy/patch_wrfxcspy.sh

@@ -26,7 +26,7 @@ DisplayHelp() {
     --wrf-branch <str>      Name of WRF branch on GitHub. Defaults to 'release-v4.6.1'.
     -c, --configure         Create new WRF configuration script.
     -d, --delete            Run make clean in source directory.
-    -p, --patch             Patch COSIPY into WRF. Does not check if already patched!
+    -p, --patch             Patch COSIPY into WRF.
     -e, --env               Load environment variables.
     -v, --verbose           Prints log messages to stderr.
     "