github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/builtins/core/io/g_doc.yaml (about)

     1  - DocumentID: g
     2    Title: >+
     3      `g`
     4    CategoryID: commands
     5    Summary: >-
     6      Glob pattern matching for file system objects (eg `*.txt`)
     7    Description: |-
     8      Returns a list of files and directories that match a glob pattern.
     9  
    10      Output is a JSON list.
    11    Usage: |-
    12      ```
    13      g pattern -> <stdout>
    14  
    15      [ <stdin> -> ] @g command pattern [ -> <stdout> ]
    16  
    17      !g pattern -> <stdout>
    18  
    19      <stdin> -> g pattern -> <stdout>
    20  
    21      <stdin> -> !g pattern -> <stdout>
    22      ```
    23    Examples: |-
    24      Inline globbing:
    25      
    26      ```
    27      cat @{ g *.txt }
    28      ```
    29  
    30      Writing a JSON array of files to disk:
    31      
    32      ```
    33      g *.txt |> filelist.json
    34      ```
    35  
    36      Writing a list of files to disk:
    37      
    38      ```
    39      g *.txt -> format str |> filelist.txt
    40      ```
    41  
    42      Checking if a file exists:
    43      
    44      ```
    45      if { g somefile.txt } then {
    46          # file exists
    47      }
    48      ```
    49  
    50      Checking if a file does not exist:
    51      
    52      ```
    53      !if { g somefile.txt } then {
    54          # file does not exist
    55      }
    56      ```
    57  
    58      Return all files apart from text files:
    59  
    60      ```
    61      !g *.txt
    62      ```
    63  
    64      Filtering a file list based on glob matches:
    65  
    66      ```
    67      f +f -> g *.md
    68      ```
    69  
    70      Remove any glob matches from a file list:
    71  
    72      ```
    73      f +f -> !g *.md
    74      ```
    75  
    76    Detail: |-
    77      ### Pattern Reference
    78  
    79      * `*` matches any number of (including zero) characters
    80      * `?` matches any single character
    81  
    82      ### Inverse Matches
    83  
    84      If you want to exclude any matches based on wildcards, rather than include
    85      them, then you can use the bang prefix. eg
    86  
    87      ```
    88      » g READ*
    89      [
    90          "README.md"
    91      ]
    92  
    93      » !g *
    94      Error in `!g` (1,1): No data returned.
    95      ```
    96  
    97      ### When Used As A Method
    98  
    99      `!g` first looks for files that match its pattern, then it reads the file list
   100      from STDIN. If STDIN contains contents that are not files then `!g` might not
   101      handle those list items correctly. This shouldn't be an issue with `frx` in its
   102      normal mode because it is only looking for matches however when used as `!g`
   103      any items that are not files will leak through.
   104  
   105      This is its designed feature and not a bug. If you wish to remove anything that
   106      also isn't a file then you should first pipe into either `g *`, `rx .*`, or
   107      `f +f` and then pipe that into `!g`.
   108  
   109      The reason for this behavior is to separate this from `!regexp` and `!match`.
   110    Synonyms:
   111    - g
   112    - "!g"
   113    Related:
   114    - rx
   115    - f
   116    - regexp
   117    - match
   118