scout-essentials 1.7.1 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b525f579cb1dfea91f74e339b0cefcc9713567e0555da3e8943cbf5e05a3a8fa
-  data.tar.gz: 75ebc6504a1aa544134f6cd83f472f4cc056d86f093eb96eea450d96e3220603
+  metadata.gz: 5fb209b3857e98d43ad106f48fc2a1da554472421349b8219f04f322954b5afa
+  data.tar.gz: 2dea338e87eac08434524e70c85a92c63091f2fe5c118b61ef387de65d9e1da9
 SHA512:
-  metadata.gz: e21bc777bae26f177ecad2aa4bcee2cd2d4b3b715b9d5fa509def84ed17ab007ff63b1f09734f506242b31d350e47f8600cbcc1a0dd544fd9932331c53572c3f
-  data.tar.gz: 3caf9cce8f443aaf892815e9ef0930490956ef53c26800b49dd12175a59ac01c34fd77bc82a492e6e64b17f6acb3e633bd95a4cf4b9ca11575b3851baf8e6169
+  metadata.gz: 4f5dfa3b79685f5b2e9ff9c0d270433e81c576113e41f17641cb858edc07b0c35e4444d7ee3bf1b588404908b07b491bd6138d8c554d329cd1d641489377b704
+  data.tar.gz: c17e0df7d59f7a8afd52d37fc7803d8da56ccd1de6e4a186f5c3665b7661064917e616b1db8dd2d8700e2f3465afd0b7d3449bc01fad604b3462891254f08fa3

data/.vimproject

@@ -1,30 +1,172 @@
 scout-essentials=/$PWD filter="*.rb *.txt *.md *.conf *.yaml" {
  LICENSE.txt
- Rakefile
+ chats=chats filter="*"{
+  review
+  document.rb
+  docs=docs{
+   Analyze Annotation tests
+   Analyze CMD and related tests
+   Analyze CMD tests
+   Analyze log tests
+   Analyze Open tests
+   Analyze Path tests
+   Analyze Persist tests
+   Analyze Resource tests
+   Analyze selected tests 
+   simple_opt, log, open, persist, cmd, tmpfile
+   
+   Analyze SimpleOpt tests
+   Analyze simple_opt tests
+   Analyze tests: simple_opt, log, open, persist, cmd, tmpfile
+   Analyze tmpfile tests
+   Analyze Utilities tests
+   Assemble Annotation docs
+   Assemble CMD docs
+   Assemble CMD docs 
+   update
+   
+   Assemble Open docs
+   Assemble Open docs 
+   update
+   
+   Assemble Path docs
+   Assemble Persist docs
+   Assemble Persist docs 
+   update
+   
+   Assemble Resource docs
+   Assemble Resource docs 
+   update
+   
+   Assemble Top-level README
+   Assemble Top-level README 
+   update
+   
+   Assemble Top-level README draft
+   Assemble Utilities docs
+   Assemble Utilities docs 
+   update
+   
+   Confirm·Explore Utilities dirs
+   Explore Annotation dirs
+   Explore CMD dirs
+   Explore Log dir
+   Explore Log lib dir
+   Explore Log lib dir 
+   refresh
+   
+   Explore Log test dir
+   Explore Log test dir 
+   refresh
+   
+   Explore Open dirs
+   Explore Path dirs
+   Explore Persist dirs
+   Explore Resource dirs
+   Explore Utilities dirs
+   Finalize README step 
+   refresh
+   
+   Finalize README.md into memory key 
+   .md
+    
+   conditional
+   
+   NEXT_STEPS
+   QA Annotation docs
+   QA CMD docs
+   QA Integrated README
+   QA Integrated README 
+   post-update
+   
+   QA Integrated README 
+   post-update
+    
+   refresh
+   
+   QA Open docs
+   QA Path docs
+   QA Persist docs
+   QA Resource docs
+   QA Utilities docs
+   Read Annotation source files
+   Read CMD source files
+   Read CMD source files 
+   refresh
+   
+   Read Log source files
+   Read Log source files 
+   iterate
+   
+   Read Log source files 
+   refresh
+   
+   Read Log source files 
+   use explorer output
+   
+   Read Open source files
+   Read Open stream and lockfile
+   Read Path source files
+   Read Persist serialize and open
+   Read Persist source files
+   Read Resource scout.rb
+   Read Resource source files
+   Read SimpleOpt source files
+   Read TmpFile and IndiferentHash source files
+   Read Utilities source files
+   Run QA Integrator on assembled docs
+   Update CMD docs 
+   assemble
+   
+   Update Open docs 
+   assemble
+   
+   Update Persist docs 
+   assemble
+   
+   Update Resource docs 
+   assemble
+   
+   Update Utilities docs 
+   assemble
+   
+   final=final{
+    annotation.md
+    cmd.md
+    open.md
+    path.md
+    persist.md
+    resource.md
+   }
+  }
+ }
+ doc=doc{
+  Annotation.md
+  CMD.md
+  ConcurrentStream.md
+  IndiferentHash.md
+  Log.md
+  NamedArray.md
+  Open.md
+  Path.md
+  Persist.md
+  Resource.md
+  SimpleOPT.md
+  TmpFile.md
+ }
  lib=lib {
   scout-essentials.rb
   scout=scout{
-   exceptions.rb
    annotation.rb
    annotation=annotation{
-    array.rb
     annotated_object.rb
     annotation_module.rb
+    array.rb
    }
-   misc.rb
-   misc=misc{
-    digest.rb
-    filesystem.rb
-    format.rb
-    helper.rb
-    insist.rb
-    monitor.rb
-    system.rb
-    math.rb
-    hook.rb
-    matching.rb
-   }
-   named_array.rb
+   cmd.rb
+   concurrent_stream.rb
+   config.rb
+   exceptions.rb
    indiferent_hash.rb
    indiferent_hash=indiferent_hash{
     case_insensitive.rb
@@ -35,42 +177,49 @@ scout-essentials=/$PWD filter="*.rb *.txt *.md *.conf *.yaml" {
     color.rb
     color_class.rb
     fingerprint.rb
+    trap.rb
     progress.rb
     progress=progress{
      report.rb
      util.rb
     }
-
-    trap.rb
-   }
-   simple_opt.rb
-   simple_opt=simple_opt{
-    accessor.rb
-    doc.rb
-    get.rb
-    parse.rb
-    setup.rb
    }
-   path.rb
-   path=path{
-    find.rb
-    tmpfile.rb
-    util.rb
+   misc.rb
+   misc=misc{
     digest.rb
+    filesystem.rb
+    format.rb
+    helper.rb
+    hook.rb
+    insist.rb
+    matching.rb
+    math.rb
+    monitor.rb
+    system.rb
    }
-   concurrent_stream.rb
-   cmd.rb
+   named_array.rb
    open.rb
    open=open{
     final.rb
     lock.rb
     remote.rb
     stream.rb
-    util.rb
     sync.rb
-    bgzf.rb
+    util.rb
+   }
+   path.rb
+   path=path{
+    digest.rb
+    find.rb
+    tmpfile.rb
+    util.rb
+   }
+   persist.rb
+   persist=persist{
+    open.rb
+    path.rb
+    serialize.rb
    }
-   tmpfile.rb
    resource.rb
    resource=resource{
     open.rb
@@ -81,12 +230,14 @@ scout-essentials=/$PWD filter="*.rb *.txt *.md *.conf *.yaml" {
     sync.rb
     util.rb
    }
-   config.rb
-   persist.rb
-   persist=persist{
-    open.rb
-    path.rb
-    serialize.rb
+   simple_opt.rb
+   tmpfile.rb
+   simple_opt=simple_opt{
+    accessor.rb
+    doc.rb
+    get.rb
+    parse.rb
+    setup.rb
    }
   }
  }
@@ -94,10 +245,6 @@ scout-essentials=/$PWD filter="*.rb *.txt *.md *.conf *.yaml" {
   test_helper.rb
   scout=scout{
    test_annotation.rb
-   annotation=annotation{
-    test_annotated_object.rb
-    test_array.rb
-    }
    test_cmd.rb
    test_concurrent_stream.rb
    test_config.rb
@@ -110,11 +257,17 @@ scout-essentials=/$PWD filter="*.rb *.txt *.md *.conf *.yaml" {
    test_persist.rb
    test_resource.rb
    test_tmpfile.rb
+   annotation=annotation{
+    test_array.rb
+    }
    misc=misc{
     test_digest.rb
     test_filesystem.rb
     test_helper.rb
+    test_hook.rb
     test_insist.rb
+    test_matching.rb
+    test_math.rb
     test_system.rb
     }
    }

data/README.md

@@ -0,0 +1,136 @@
+# scout-essentials
+
+scout-essentials is the core library of the Scout framework. It provides a small, focused set of primitives used across the rest of the Scout ecosystem: process/stream management, file and path utilities, persistence and caching, logging and progress reporting, lightweight annotations for objects, and simple option parsing. The additional, domain-level functionality lives in companion packages such as `scout-gear`, `scout-ai`, etc. — see the mikisvaz GitHub account for those repositories.
+
+This README points you to the key modules, shows quick usage patterns and explains where to find more detailed documentation in the `doc/` directory.
+
+## Overview
+
+Core capabilities included in scout-essentials:
+
+- Process and stream management with safe concurrency: `ConcurrentStream`, `CMD`
+- Robust file/stream I/O and remote access: `Open`
+- File/path abstraction and package-oriented lookup: `Path`, `Resource`
+- Atomic persistence and caching: `Persist`, `TmpFile`
+- Logging, color output and progress reporting: `Log`
+- Lightweight typed annotations on arbitrary objects: `Annotation`, `NamedArray`
+- Flexible indifferent Hash and option helpers: `IndiferentHash`, `SimpleOPT` (SOPT)
+
+Each module is documented in the repository `doc/` directory; see the "Documentation" section below for direct links.
+
+---
+
+## Documentation
+
+Full module-level documentation is shipped in `doc/`. The most important documents are:
+
+- doc/Annotation.md — add typed annotations to objects and arrays; AnnotatedArray
+- doc/CMD.md — process execution, streaming, tool discovery and helper wrappers
+- doc/ConcurrentStream.md — concurrent stream lifecycle, joining, aborting and callbacks
+- doc/IndiferentHash.md — string/symbol indifferent Hash helpers and options utilities
+- doc/Log.md — logging, colors, fingerprinting and ProgressBar
+- doc/NamedArray.md — small record-like arrays with named fields and fuzzy matching
+- doc/Open.md — unified file/stream I/O, remote fetch (wget/ssh), atomic writes, sync
+- doc/Path.md — Path helpers, mapping, finding and extension utilities
+- doc/Persist.md — typed serialization, persistence/caching and `Persist.persist`
+- doc/Resource.md — resource production, claim/produce and rake-based producers
+- doc/SimpleOPT.md — small option parsing and usage generation (SOPT)
+- doc/TmpFile.md — temporary file/dir helpers and stable cache path generator
+
+Open those files for detailed API descriptions, examples and notes.
+
+---
+
+## Quick start (examples)
+
+These short snippets show typical usage patterns — the docs in `doc/` contain more detail and examples.
+
+Annotation:
+```ruby
+module Tag
+  extend Annotation
+  annotation :code, :note
+end
+
+s = "hello"
+Tag.setup(s, :code)    # s.code -> :code
+s2 = "other"
+s.annotate(s2)         # copies annotations
+```
+
+Open (reading a file, auto-decompress):
+```ruby
+content = Open.read("data.tsv.gz")
+```
+
+Persist (cache a computed value):
+```ruby
+value = Persist.persist("my-result", :json, dir: Path.setup("var/cache")) do
+  expensive_computation()
+end
+```
+
+CMD + ConcurrentStream (run a pipeline):
+```ruby
+io = CMD.cmd("tail -n 100", :in => some_file_io, :pipe => true)
+io2 = CMD.cmd("grep foo", :in => io, :pipe => true)
+puts io2.read
+io2.join
+```
+
+Log + ProgressBar:
+```ruby
+Log::ProgressBar.with_bar(100, desc: "Working") do |bar|
+  100.times { bar.tick; work_item }
+end
+```
+
+Path + Resource:
+```ruby
+# Resource modules typically claim resources and produce them on demand.
+# Accessing a Path calls produce, so opening a resource Path triggers creation.
+p = Path.setup("share/data/myfile", 'mypkg')
+p.produce
+Open.read(p)
+```
+
+---
+
+## Running tests
+
+The test suite exercises the modules (unit tests use Test::Unit). To run the tests in this repository, use your normal Ruby test runner; the test files are under `test/` — examples:
+
+```bash
+# from repository root
+ruby -Ilib test/scout/test_tmpfile.rb
+# or run the whole suite with your preferred runner
+```
+
+Tests in the suite show practical usages and edge cases for the provided utilities.
+
+---
+
+## Related projects
+
+scout-essentials is intentionally focused on low-level primitives. Higher-level, domain-specific functionality is implemented in companion projects maintained on the mikisvaz GitHub account (look for repositories named `scout-gear`, `scout-ai`, etc.). Those packages build on what you find here to provide workflows, tools and integrations.
+
+GitHub: https://github.com/mikisvaz  
+Look for repositories that begin with `scout-` (e.g. `scout-gear`, `scout-ai`).
+
+---
+
+## Contributing
+
+Contributions and improvements are welcome. Please follow the repository contribution guidelines (if present) or submit issues / pull requests on the project repository.
+
+If you extend or reuse code from this package in companion packages, prefer to keep core primitives here and implement domain logic in separate modules/packages (as done by the Scout ecosystem).
+
+---
+
+## License
+
+See the repository LICENSE (if present) for licensing information.
+
+---
+
+If you need help finding a specific API, open the corresponding file in `doc/` (listed above) or search the `lib/` tree for concrete implementations and tests in `test/` for usage examples.

data/Rakefile

@@ -20,6 +20,7 @@ Juwelier::Tasks.new do |gem|
   gem.add_runtime_dependency 'term-ansicolor'
   gem.add_runtime_dependency 'yaml'
   gem.add_runtime_dependency 'rake'
+  gem.add_runtime_dependency 'listen'
 end
 Juwelier::RubygemsDotOrgTasks.new
 require 'rake/testtask'

data/VERSION

@@ -1 +1 @@
-1.7.1
+1.8.0