From cb080d7d11ebd84e21fdac0d3b8f6c2b12df5ae3 Mon Sep 17 00:00:00 2001 From: LilyWhite Date: Feb 04 2023 13:42:24 +0000 Subject: refactor: no longer use class-based architecture --- diff --git a/README.md b/README.md index add51be..24677ba 100644 --- a/README.md +++ b/README.md @@ -1,63 +1,9 @@ # Orca -Orca is a pure-fish library that implements many utilities for fish. +Orca is a library that implements many utilities for [fish](https://fishshell.com). -Currently orca supports (or plan to support) the following features. +Currently Orca supports (or plan to support) the following features. -- [] Dictionaries (via the `dict` command) -- [] Object Orientation +- [] Object Orientation (Prototypes) - [] A module/namespace system +- [] A minimal type system -## Documentation -Please refer to the source code for thorough explanations on the inner workings of orca. - -### General Rules -All variable names under the prefix `__orca_` are considered reserved. -You should not use them, nor should you depend on their values for anything. - -If you use anything from this library, you MUST run `orca::init` as the first -command of your executable script. A suggested template is: - -```fish -source "/path/to/orca.fish" -source "/your/library.fish" - -function main - # your script -end - -orca::init -main $argv # Pass along command line options -``` - -Orca uses `::` as its pseudo namespace (pseudospace) -separator, this is intentionally different from fish's `_`, so that you know -who is provided by Orca. -### Dictionaries -Dictionaries are implemented by mangling variable names. It is similar to hashes in Perl. - - - -### Object Orientation -Orca uses a class-based OO model. It provides helper commands in the `orca::oo` pseudospace. - -#### How it works -The `orca::oo::class` command defines a class. - -Functions with names matching `Class::` and `Class.` are recognized as methods. -`::` defines a _class method_ and `.` defines an _instance method_. If `` starts with an -underscore, it is considered private. - -Class definitions MUST be ended with a matching `orca::oo::endclass`. This command loads previously -defined functions into orca's internal registry for object commands to query. After doing so, it -mangles the name of the functions (transforming them to a random name like `_orca_class_Animal_2PQN712`) -to prevent accidental calling. The `orca::init` command checks for unmatching `class..endclass` pairs -in a rudimentary way (it only asserts that the total numbers are correct). - -Orca uses single inheritance. It provides mixins (called roles) as an alternative to multiple inheritance. -Roles are similarly defined, using `orca::oo::role` and `orca::oo::endrole`. Defining a `_constructor` method -for roles result in an error since roles can never be initialized. - -Arguments passed to `orca::oo::class` define a class's attributes. It does NOT use conventional -`-o, --option` shell format to ease readability. - -`is BASECLASS` defines is-a inheritance, and `does ROLE` diff --git a/doc/doctool.md b/doc/doctool.md new file mode 100644 index 0000000..f90c8c6 --- /dev/null +++ b/doc/doctool.md @@ -0,0 +1,12 @@ +# Documenting your program + +Orca includes a documentation tool to generate `--help` for your fish functions. + +The `@doc` command accepts a single argument: path to your documentation file. +When `@doc` is present, the function will display the help file and exit if its sole argument is +`--help`. It also adds that path to the orcadoc database. + +The `orcadoc` program included with the Orca distribution may be used to view the documentations. + +Documentation files are simply fish scripts that print out the documentation. You may use `set_color` +to tweak how your documentation looks like. diff --git a/doc/getting-started.md b/doc/getting-started.md new file mode 100644 index 0000000..5681ae0 --- /dev/null +++ b/doc/getting-started.md @@ -0,0 +1,21 @@ +# Getting Started +## Installing +The simplest way is from the download site, + +```sh +curl -sSL https://orca.lilywhite.dev/install | bash +``` + +or grab the latest main branch using git. + +```sh +git clone https://pagure.io/orca.git +cd orca +./install +``` + +## General Rules +All variable names under the prefix `__orca_` are considered reserved. + +You should not use them, nor should you depend on their values for anything. + diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 0000000..c7d20d2 --- /dev/null +++ b/doc/index.md @@ -0,0 +1,4 @@ +# Orca Documentation +Please refer to the source code for thorough explanations on the inner workings of orca. + + diff --git a/doc/table.md b/doc/table.md new file mode 100644 index 0000000..f91505a --- /dev/null +++ b/doc/table.md @@ -0,0 +1 @@ +# Table diff --git a/example/animal.fish b/example/animal.fish index 0cf1ea2..40ff5e9 100644 --- a/example/animal.fish +++ b/example/animal.fish @@ -1,4 +1,4 @@ -orca::oo::class Animal +@class Animal function Animal::_constructor argparse '-n/--name=' $argv @@ -6,4 +6,4 @@ function Animal::_constructor end -orca::oo::endclass +@endclass diff --git a/src/dict.fish b/src/dict.fish deleted file mode 100644 index 2d75e7c..0000000 --- a/src/dict.fish +++ /dev/null @@ -1,11 +0,0 @@ -# This implements an associative array using variable name magic -# Values are stored in __orca_dict__ - -function _dict::set - -end - -function _dict::new - argparse 's/setflags=' -- $argv; or return - -end