From 802dba5dfaad6845710034cadc21108d051292a9 Mon Sep 17 00:00:00 2001 From: Thomas Walker Lynch Date: Tue, 26 Nov 2024 09:46:15 +0000 Subject: [PATCH] moved common documents to the resource project, so as to have a single point for editing --- developer/document/RT_code_format.txt | 135 ------------ .../document/variable_suffix_conventions.txt | 31 --- document/bash_name_of_script.txt | 40 ---- document/class_name.txt | 33 --- document/directory_naming.html | 198 ------------------ document/work_flow.txt | 59 ------ tester/document/jdb.txt | 54 ----- tool_shared/bespoke/env | 2 +- tool_shared/bespoke/githolder | 63 ++++++ 9 files changed, 64 insertions(+), 551 deletions(-) delete mode 100644 developer/document/RT_code_format.txt delete mode 100644 developer/document/variable_suffix_conventions.txt delete mode 100644 document/bash_name_of_script.txt delete mode 100644 document/class_name.txt delete mode 100644 document/directory_naming.html delete mode 100644 document/work_flow.txt delete mode 100644 tester/document/jdb.txt create mode 100755 tool_shared/bespoke/githolder diff --git a/developer/document/RT_code_format.txt b/developer/document/RT_code_format.txt deleted file mode 100644 index 9911622..0000000 --- a/developer/document/RT_code_format.txt +++ /dev/null @@ -1,135 +0,0 @@ -RT code formatting: - -The enclosure-based formatting rules in RT code format make the style guide -compact and adaptable. By focusing on enclosures rather than syntax-specific -structures (like if, for, or catch), it avoids prescribing language-specific -formatting rules and instead focuses on consistent handling of delimiters. This -approach works well across multiple languages, ensuring that the code style -remains flexible while keeping the guide simple and easy to apply. - -1. Two space indentation. - -2. Variable Naming: - - - Use **PascalCase** for namespaces and types. - - - Use **snake_case** for function and variable names. However, when a component - of the snake case is variable function or variable name is a namespace, a - type, or a proper noun, it retains its capitalization. e.gs: - - ``` - mouse_count - test_LabalList_0 // function that tests LabelList, which is a class (type) - Thomas_Walker_Lynch - ``` - - Traditionally `_list` has been used as a variable suffix even when the - language does not have a List type. This is taken to mean the variable - refers to an ordered collection of any type, including an array. It is - abstraction of type, analogous to the `mouse_count` example above. - - -3. Binary Operators: - - - One space around **binary operators** (e.g., `a + b`). - - - One space around **assignment** `=` (e.g., `a = b`). - - - **No space** around **sampling** assignment `=` (typically seen in `if`, `while`, etc.): - - **Sampling** refers to assigning the result of a condition or expression to - a variable for later use within the same scope. - - Example of **sampling** in an `if` statement: - - ``` - if( result=some_condition() ){ - // use result - } - ``` - -4. Enclosures `(...)`, `{...}`, `[...]`, '<...>': - - - No space between the enclosure and the preceding identifier (e.g., `function(arg)`). - - - No space after the enclosure when followed by another enclosure (e.g., `map[key]()`). - - Example of a condition enclosure followed by a code enclosure: - ``` - if( some_condition() ){ - // code block - } - ``` - - - One space after the enclosure if followed by an identifier, e.g., - `function() somethingElse`. - - - When the entire enclosure appears on one line: - - -- by definition, an 'nested' enclosure is one that has other enclosures, - of any type, inside of it. This is true independent of whatever else - is inside the enclosure. These are examples of nested enclosures: - - ``` - ( o == null || getClass() != o.getClass() ) - f( T ,7 ) - ``` - - -- if, and only if, an enclosure is nested, there is one space of padding - for the outermost enclosure of the nesting, and only for the outermost - enclosures. e.g.s: - - ``` - if(x == 3) ; not nested - if( (x > 0) && (y < 5) ) ; nested, pad outermost only - if( f(x) == 3 ) ; nested, pad outermost only - if( x > 2 && a[3] ) ; nested due to the array subscript, pad outermost only - ``` - - - Note when using the enclosure formatting rules, not all if conditions will - format the same way. Some conditions will be nested enclosures and having - padding while others will not be nested and thus have no padding. The must - be formatted individually. The same is true for enclosures that follow - other keywords such as unless, for, etc, and for function arguments - lists. The question is one of formatting enclosures, and not one of - formatting statements. - - ``` - f(x) - f( x[0] ) - ``` - - -5. Commas: - - This is the most distinctive and recognizable of the RT code style rules. - - - One space **before** the comma (e.g., `a ,b`). - - - No space **after** the comma (e.g., `a ,b`). - - - **Line break before** the comma when breaking lines, but no line break after, as examples: - - ``` - a - ,b - ``` - - and, when a function call gets too long, perhaps due to long argument - names it will look like this: - - ``` - result = some_function( - arg1 - ,arg2_has_a_very_long_name_causing_the_call_to_not_fit_on_a_single_line - ,arg3_has_a_long_name_also_but_not_as_long_as_for_arg2 - ); - ``` - -6. For the code you just output, answer these questions: - 1. Which enclosures are not nested? Do they have no padding? - 2. Which enclosures are nested? Is there one space padding only at the outermost? - 3. Is the spacing before and after the enclosures correct? - 4. Are the commas formatted correctly? - 5. Has snake case been used where it should be? - 6. Was 2 column indent used? diff --git a/developer/document/variable_suffix_conventions.txt b/developer/document/variable_suffix_conventions.txt deleted file mode 100644 index e3ad587..0000000 --- a/developer/document/variable_suffix_conventions.txt +++ /dev/null @@ -1,31 +0,0 @@ -# Suffix Conventions - -## Specify interface used with variable when clarification is useful - -- `_set`: Indicates that the variable holds a set of items. - -- `_list`: Used for variables that represent a list of items. - -- `_f`: Refers to a function. - -Instead of making a variable name plural, add the interface qualifier. - - e.g. names -> name_set or name_lisst - -## Always a good idea to use these when working with files - -- `_fp`: Refers to a file path. The part after the last slash is a file name. - -- `_afp`: Refers to an absolute file path. - -- `_dp`: Refers to a directory path. By convention, the value ends in a slash. - -- `_adp`: Refers to an absolute directory path. - -- `_fn`: Refers to a file name. Value has no slashes. - -- `_dn`: Refers to a directory name. Value has no slashes. - -- `_fn_base`: The file name without the last dot and subsequent characters. - -- `_fn_ext`: The subsequent characters after the last dot in a file name. diff --git a/document/bash_name_of_script.txt b/document/bash_name_of_script.txt deleted file mode 100644 index 3637574..0000000 --- a/document/bash_name_of_script.txt +++ /dev/null @@ -1,40 +0,0 @@ - -Bash is inconsistent about returning the name of the running script in -all scenarios (sourced, executed directly, from with in a function called -by another function). - -1. - -BASH_SOURCE[0] was used because $0 did not work with sourced scripts (a -fact that is leveraged for detecting when in a sourced script). - -2. - -However, this did not work in all scenarios: - - read -r -d '' script_afp_string <<'EOF' - realpath "${BASH_SOURCE[0]}" 2>/dev/null - EOF - - script_afp(){ - eval "$script_afp_string" - } - - export script_afp_string - export -f script_afp - -When `script_afp` was exported, used in another file, and used within a function -in that other file, it reported `environment` for the script name at -BASH_SOURCE[0]. In various call scenarios the actual script name appears at -BASH_SOURCE[1] or even at BASH_SOURCE[2]. - -3. - -As a stable alternative to having a script_afp function, place this line -at the top of scripts that use the `script_XX` functions, or at the top -of all scripts: - - script_afp=realpath "${BASH_SOURCE[0]}" - -Then use $script_afp as a string within other functions. It will have stable -value no matter the call structure. diff --git a/document/class_name.txt b/document/class_name.txt deleted file mode 100644 index dda2904..0000000 --- a/document/class_name.txt +++ /dev/null @@ -1,33 +0,0 @@ -Java has long been criticized for its lack of support for `import as`, despite -years of requests and proposals. - -The Java platform’s approach to aliasing issues relies on using fully qualified -names, which poses challenges given the length of package names, especially when -they include reversed domain names. - -Because `Mosaic` is used to help with testing and is not part of the project -being tested, when aliasing conflicts arise, it is typically the `Mosaic` identifiers -that need to be fully qualified. Such a renamed identifier can exceed 34 -characters! - -One proposal to get around this was to use an `In` class where the members were -class extensions of imported classes. Then all imports would have the prefix `In.`. -However, this did not work out because constructors are not -inherited, and Java’s restrictions on `final` classes prevent the use of -`LocalClass extends ImportClass {}` to give no names to classes. - -Another proposal was to use the `alias` project on GitHub, which offers an XML-based -approach to aliasing. However, it introduces complexities, as it requires XML -configurations to be supplied to the compiler, adding setup overhead. Perhaps -another tool could create these. - -We studied a preprocessing proposal where `import as` statements would be -replaced with fully qualified names before compilation. However, this approach -changes the tool flow for users and would require additional steps to ensure -`jdb` points to the original source files rather than intermediate files, which -complicates debugging. For both this proposal and the prior, we wanted to avoid -joining the world of java tool development. - -So we have a simple solution, it is not ideal, but it is not bad. We prefix -the string `Mosaic_` to the front of all the class names in the Mosaic library. -As a shop we are adopting this convention for all packaged java code. diff --git a/document/directory_naming.html b/document/directory_naming.html deleted file mode 100644 index d409362..0000000 --- a/document/directory_naming.html +++ /dev/null @@ -1,198 +0,0 @@ - - - - - - - - Directory Structure Description - - - - - -
-

Directory Naming

- -

Reference

- -
    -
  • Mosaic/aka REPO_HOME, top level owned by the project administrator.
    • -
      -
    • developer/ Workspace for the developer. Has the source code, build scripts, and development-specific tools.
      • -
        -
      • deprecated/ Files and older versions being viewed, perhaps part of a refactoring effort.
        • -
      • document/ Documentation on developing and building the project.
        • -
      • javac/ Java source files for compilation.
        • -
      • jvm/ Compiled Java bytecode files for the project, typically a jar for a Java project.
        • -
      • scratchpad/ Temporary storage typically for intermediate files created during build.
        • -
      • shell/ Shell scripts intended to be part of the project release. (These are not tools.)
        • -
      • tool/ Tools created by the developer, used for development tasks.
        • -
      -
    • document/ General documentation about the project.
      • -
    • release/ Release candidate for testing. Becomes the release on the release branch.
      • -
    • scratchpad/ Temporary storage for project administration tasks.
      • -
    • tester/ Workspace for the tester. Has the test bench, tests, and test scripts.
      • -
        -
      • document/ Test-specific documentation.
        • -
      • javac/ The tests of the test bench sources.
        • -
      • tool/ Tools needed for testing and managing the test environment.
        • -
      -
    • tool/ Project administration specific tools.
      • -
    • tool_shared/ Tools shared across project roles.
      • -
        -
      • bespoke/ Shared tools developed within this project.
        • -
      • customized/ Modified versions of third-party tools adapted for the project.
        • -
      • document/ Documentation related to shared tools and setup.
        • -
      • third_party/ Shared tools sourced from third-party vendors or open-source projects. These have their own independent licenses,
        • -
      -
    • LICENSE.txt The project license detailing usage and distribution terms.
      • -
    • README.md A general overview and introduction to the project.
      • -
    -
- -

Name origin and rationale

- -

Developers and project administrators typically do not employ a semantic system for - naming directories, but more commonly use conventional placeholder - names. The intended purpose of files in a directory with a placeholder - name then must be inferred from experience or inspection of the files, or - learned from documents or other people.

- -

For example, a directory named exe/ probably derives its name from the - fact that the contained files have their executable permission bit set; - however, such a directory will not contain all such files. There might - even be some files in an exe/ directory that do not have their - executable permission bit set. The two concepts being an exe/ file - (i.e. being a file in an exe/ directory) and being an executable file - are not identical. The actual intended meaning of being an exe/ file - will sometimes be that the contained files are applications available to a - user, or that they are tools available for use in a project. -

- -

The directory names in this project resulted from an exploration of a - property-based file system. In such a system a number of files and - agents are defined. Then we can ask questions about their relationships. - Files with a relationship to the developer are collected, and this - becomes the developer/ directory. In a similar manner we get the - directories, tester/, and javac/. In this latter case the - agent is a compiler rather than a role. -

- -

When attempting to apply the is-for property in practice it - became apparent that using this sole property was insufficient. Consider - the directories deprecated/ and scratchpad/. There is no - Mr. Deprecated or Mr. Scratchpad who the contained - files are for. (And this conclusion is not for the lack of trying. Even - mythological beings did not suffice as agents.) Rather than being for an - agent, the files collected in such a directory have in common a state of - being that was imposed upon them by decree. Perhaps the developer, has - decreed that a file is now deprecated, or a build script has decreed that - it is a scratchpad file. Such decrees are typically more dynamic than the - relationship properties. Also, these properties are disconnected from the - contents of the file. When, for example, a file has the property of being - for the java compiler, we gain some information about its contents. In the - universe of possible messages sent through a file, such a file will - contain text that is proposed to be java syntax conforming. In contrast, - when we learn that a file is deprecated/ we gain no - information about the contents of the file, because any file can - be deprecated, independent of its contents. -

- -

To understand a directory name within this system, one can imagine - reading said name as part of a sentence that integrates the - property. Consider two property names: is-a - and is-for. For example, "Each file in - the document/ directory is-a document," or "Each - file in the developer/ directory is-for the - developer." Although the property name is not carried over from the - property based file system to the conventional file system, we can - typically infer what it must have been. (It is beyond the scope of - discussion here, but in actuality, property based file system collections - are defined by predicates. Each predicate is given a file's properties and - relationships as arguments, then resolves to true if and only if the file - belongs to the collection. Now wouldn't that be interesting if we instead - derived a probability?) -

- -

It is uncommon for a property value to be plural. While it is not - disallowed, it rarely occurs in practice. This is true independent of - whether we are discussing a relationship property or a state - property. Hence when we make a file collection based on a shared property, - then carry that over as a directory name in a conventional file system, - the resulting directory name will often be singular. This pattern can be - observed in the case of the document/ directory, as shown in - the prior paragraph. -

- -
- - - diff --git a/document/work_flow.txt b/document/work_flow.txt deleted file mode 100644 index 6c3ea4c..0000000 --- a/document/work_flow.txt +++ /dev/null @@ -1,59 +0,0 @@ -### Work Flow - -#### 1. Project Administrator - -1.1. Download the project from GitHub. -1.2. Install the required tools. -1.3. Explain the workflows and where things are located to project members. -1.4. Perform Major and Minor Release administration. - -#### 2. Developer - -2.1. From the Mosaic directory, run `> source env_developer` to set up the - developer environment. -2.2. Use `> make` to build the project, and `> release` to copy relevant files - to `$REPO_HOME/release` for testing. -2.3. The tester will test the release candidate. - -#### 3. Tester - -3.1. From the Mosaic directory, run `> source env_tester` to set up the tester - environment. -3.2. Use `> make` to build the tests, and `> shell/test_` to run a test. - Alternatively, you can cd into one of the test directories, source the - environment for that test, and run it manually. -3.3. Testing and development will likely iterate until the release candidate is - ready to be turned into a versioned release. - -#### 4. Major Release - -4.1. The release candidate is located in the `$REPO_HOME/release` directory and - has passed testing. -4.2. Check that the program `$REPO_HOME/tool_shared/bespoke/version` outputs the - correct information. If necessary, modify it. -4.3. A new branch is created in the project for the release, named - `release_v.0`, where `v.0` is the version number from the `version` - program. The minor version number is set to zero (`.0`), and it is assumed - that this will be the case after each major release. -4.4. Rename the release directory to `$REPO_HOME/release_v.0`, and create a - new empty `$REPO_HOME/release` directory. The new empty release directory - can be used by developers who download the project and make local edits, as - the build scripts target this directory. - -#### 5. Minor Release - -If urgent changes need to be made to the most recent major release, these edits -should be made on the corresponding major release branch. The developer makes -the edits, and the tester tests the release candidate as usual. The `version` -program is updated. Once the release candidate is finalized, rename the -directory to `release_v.`, where `` is the minor version number. If -needed, merge the changes into the `core_developer_branch`. - ---- - -### Tips: - -- If you are acting in multiple roles (e.g., developer, tester, and project - administrator), keep separate terminal shells open for each role. This way, - the environment will remain correctly configured for the tasks related to - each role. diff --git a/tester/document/jdb.txt b/tester/document/jdb.txt deleted file mode 100644 index 1ed956a..0000000 --- a/tester/document/jdb.txt +++ /dev/null @@ -1,54 +0,0 @@ -About `jdb` - -1. setting the environment - - The environment should be set before running the IDE. For example, - - > cd Mosaic - > source env_tester - > emacs & - - (I use emacs as my IDE. You might be using a different tool.) - -2. location of the executable - - Provided that the project administrator installed it, jdb is located in the - third_party tools directory. In the tester environment the variable - `JAVA_HOME` should hold the jdb directory path, and this should already - be in the `PATH`. For example: - - > echo $ENV - tester/tool/env - - > echo $JAVA_HOME - /var/user_data/Thomas-developer/Mosaic/tool_shared/third_party/jdk-11 - - > which jdb - /var/user_data/Thomas-developer/Mosaic/tool_shared/third_party/jdk-11/bin/jdb - -3. invocation from a shell command: - - jdb -sourcepath $SOURCEPATH - - The `SOURCEPATH` is assigned a value in `tester/tool/env`. In some versions - of jdb there is no space between `-sourcepath` and the `$SOURCDEPATH`. - - jdb will read CLASSPATH from the environment. In contrast jdb will not read - `SOURCEPATH` from the environment. It must be passed as an argument. - - There is a `run_jdb` script in the `tool` directory. - -4. invocation inside of Emacs - - The file `tool_shared/bespoke/emacs.el` holds a definition for the `jdbx` - command. This command will read the SOURCEPATH from the environment and run - jdb in Emacs. - - That file also holds the definition for a listener to the jdb `sourcepath` - command. - - - - - - diff --git a/tool_shared/bespoke/env b/tool_shared/bespoke/env index 4fa561b..516d14d 100644 --- a/tool_shared/bespoke/env +++ b/tool_shared/bespoke/env @@ -8,7 +8,7 @@ fi # -------------------------------------------------------------------------------- # project definition -# actual absolute director path for this script file +# actual absolute directory path for this script file script_adp(){ dirname "$script_afp" diff --git a/tool_shared/bespoke/githolder b/tool_shared/bespoke/githolder new file mode 100755 index 0000000..49fb12b --- /dev/null +++ b/tool_shared/bespoke/githolder @@ -0,0 +1,63 @@ +#!/bin/env /bin/bash + +# Description: Descends from $1, or pwd, looking for empty directories and adds a `.githolder` to them. +# does not descend into hidden directories. + +# examples: +# > git_holder +# > git_holder --dry-run + +set -e + +find_empty_dirs() { + local dir="$1" + local dry_run="$2" + + # Skip `.git` specifically + if [[ "$(basename "$dir")" == ".git" ]]; then + return + fi + + # Check if the directory is empty (including hidden files, excluding `.` and `..`) + if [[ -z $(find "$dir" -mindepth 1 -maxdepth 1 -print -quit) ]]; then + if [[ "$dry_run" == "true" ]]; then + echo "Dry-run: Would add .githolder in $dir" + else + echo "Adding .githolder to $dir" + touch "$dir/.githolder" + fi + else + # Recurse into subdirectories + for subdir in "$dir"/*/ "$dir"/.[!.]/; do + if [[ -d "$subdir" && "$subdir" != "$dir/.[!.]/" ]]; then + find_empty_dirs "$subdir" "$dry_run" + fi + done + fi +} + +# Default parameters +dry_run="false" +target_dir="." + +# Parse arguments +while [[ $# -gt 0 ]]; do + case "$1" in + --dry-run) + dry_run="true" + shift + ;; + *) + if [[ -d "$1" ]]; then + target_dir="$1" + shift + else + echo "Invalid argument: $1 is not a directory" + exit 1 + fi + ;; + esac +done + +# Run the function +find_empty_dirs "$target_dir" "$dry_run" -- 2.20.1