Skip to content
This repository was archived by the owner on Dec 7, 2023. It is now read-only.

Commit fe4b504

Browse files
jclemjclem
authored
Merge pull request #2 from jclem/fix-docs
Update documentation
2 parents 4f0af07 + 4235abd commit fe4b504

File tree

8 files changed

+182
-18
lines changed

8 files changed

+182
-18
lines changed

‎.credo.exs‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# This file contains the configuration for Credo and you are probably reading
2+
# this after creating it with `mix credo.gen.config`.
3+
#
4+
# If you find anything wrong or unclear in this file, please report an
5+
# issue on GitHub: https://github.com/rrrene/credo/issues
6+
#
7+
%{
8+
#
9+
# You can have as many configs as you like in the `configs:` field.
10+
configs: [
11+
%{
12+
#
13+
# Run any config using `mix credo -C <name>`. If no config name is given
14+
# "default" is used.
15+
name: "default",
16+
#
17+
# These are the files included in the analysis:
18+
files: %{
19+
#
20+
# You can give explicit globs or simply directories.
21+
# In the latter case `**/*.{ex,exs}` will be used.
22+
included: ["lib/"],
23+
excluded: [~r"/_build/", ~r"/deps/"]
24+
},
25+
#
26+
# If you create your own checks, you must specify the source files for
27+
# them here, so they can be loaded by Credo before running the analysis.
28+
requires: [],
29+
#
30+
# Credo automatically checks for updates, like e.g. Hex does.
31+
# You can disable this behaviour below:
32+
check_for_updates: true,
33+
#
34+
# If you want to enforce a style guide and need a more traditional linting
35+
# experience, you can change `strict` to `true` below:
36+
strict: true,
37+
#
38+
# If you want to use uncolored output by default, you can change `color`
39+
# to `false` below:
40+
color: true,
41+
#
42+
# You can customize the parameters of any check by adding a second element
43+
# to the tuple.
44+
#
45+
# To disable a check put `false` as second element:
46+
#
47+
# {Credo.Check.Design.DuplicatedCode, false}
48+
#
49+
checks: [
50+
{Credo.Check.Consistency.ExceptionNames},
51+
{Credo.Check.Consistency.LineEndings},
52+
{Credo.Check.Consistency.MultiAliasImportRequireUse},
53+
{Credo.Check.Consistency.ParameterPatternMatching},
54+
{Credo.Check.Consistency.SpaceAroundOperators},
55+
{Credo.Check.Consistency.SpaceInParentheses},
56+
{Credo.Check.Consistency.TabsOrSpaces},
57+
58+
# For some checks, like AliasUsage, you can only customize the priority
59+
# Priority values are: `low, normal, high, higher`
60+
{Credo.Check.Design.AliasUsage, priority: :low},
61+
62+
# For others you can set parameters
63+
64+
# If you don't want the `setup` and `test` macro calls in ExUnit tests
65+
# or the `schema` macro in Ecto schemas to trigger DuplicatedCode, just
66+
# set the `excluded_macros` parameter to `[:schema, :setup, :test]`.
67+
{Credo.Check.Design.DuplicatedCode, excluded_macros: []},
68+
69+
# You can also customize the exit_status of each check.
70+
# If you don't want TODO comments to cause `mix credo` to fail, just
71+
# set this value to 0 (zero).
72+
{Credo.Check.Design.TagTODO, exit_status: 2},
73+
{Credo.Check.Design.TagFIXME},
74+
75+
{Credo.Check.Readability.FunctionNames},
76+
{Credo.Check.Readability.LargeNumbers},
77+
{Credo.Check.Readability.MaxLineLength, priority: :low, max_length: 80},
78+
{Credo.Check.Readability.ModuleAttributeNames},
79+
{Credo.Check.Readability.ModuleDoc},
80+
{Credo.Check.Readability.ModuleNames},
81+
{Credo.Check.Readability.NoParenthesesWhenZeroArity},
82+
{Credo.Check.Readability.ParenthesesInCondition},
83+
{Credo.Check.Readability.PredicateFunctionNames},
84+
{Credo.Check.Readability.PreferImplicitTry},
85+
{Credo.Check.Readability.RedundantBlankLines},
86+
{Credo.Check.Readability.Specs},
87+
{Credo.Check.Readability.StringSigils},
88+
{Credo.Check.Readability.TrailingBlankLine},
89+
{Credo.Check.Readability.TrailingWhiteSpace},
90+
{Credo.Check.Readability.VariableNames},
91+
{Credo.Check.Refactor.DoubleBooleanNegation},
92+
93+
# {Credo.Check.Refactor.CaseTrivialMatches}, # deprecated in 0.4.0
94+
{Credo.Check.Refactor.ABCSize},
95+
{Credo.Check.Refactor.CondStatements},
96+
{Credo.Check.Refactor.CyclomaticComplexity},
97+
{Credo.Check.Refactor.FunctionArity},
98+
{Credo.Check.Refactor.MatchInCondition},
99+
{Credo.Check.Refactor.NegatedConditionsInUnless},
100+
{Credo.Check.Refactor.NegatedConditionsWithElse},
101+
{Credo.Check.Refactor.Nesting},
102+
{Credo.Check.Refactor.PipeChainStart},
103+
{Credo.Check.Refactor.UnlessWithElse},
104+
{Credo.Check.Refactor.VariableRebinding},
105+
106+
{Credo.Check.Warning.BoolOperationOnSameValues},
107+
{Credo.Check.Warning.IExPry},
108+
{Credo.Check.Warning.IoInspect},
109+
{Credo.Check.Warning.NameRedeclarationByAssignment},
110+
{Credo.Check.Warning.NameRedeclarationByCase},
111+
{Credo.Check.Warning.NameRedeclarationByDef},
112+
{Credo.Check.Warning.NameRedeclarationByFn},
113+
{Credo.Check.Warning.OperationOnSameValues},
114+
{Credo.Check.Warning.OperationWithConstantResult},
115+
{Credo.Check.Warning.UnusedEnumOperation},
116+
{Credo.Check.Warning.UnusedFileOperation},
117+
{Credo.Check.Warning.UnusedKeywordOperation},
118+
{Credo.Check.Warning.UnusedListOperation},
119+
{Credo.Check.Warning.UnusedPathOperation},
120+
{Credo.Check.Warning.UnusedRegexOperation},
121+
{Credo.Check.Warning.UnusedStringOperation},
122+
{Credo.Check.Warning.UnusedTupleOperation},
123+
124+
# Custom checks can be created using `mix credo.gen.check`.
125+
#
126+
]
127+
}
128+
]
129+
}

‎README.md‎

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
1-
# Ot
1+
# OT
22

3-
**TODO: Add description**
3+
This Elixir library contains an implementation of
4+
[operational transformation][ot] for strings. It is the same general algorithm
5+
as [ottypes/text][ot_text], but made invertible.
46

57
## Installation
68

@@ -13,7 +15,21 @@ def deps do
1315
end
1416
```
1517

16-
Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
17-
and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
18-
be found at [https://hexdocs.pm/ot](https://hexdocs.pm/ot).
18+
Documentation can be generated with
19+
[ExDoc](https://github.com/elixir-lang/ex_doc) and published on
20+
[HexDocs](https://hexdocs.pm). Once published, the docs can be found at
21+
[https://hexdocs.pm/ot](https://hexdocs.pm/ot).
1922

23+
## Testing
24+
25+
To run the basic tests, run `mix test`. There are also some longer fuzz tests
26+
available that are quite slow. These can be included in the suite by running
27+
`mix test --include slow_fuzz`.
28+
29+
This repo also has [Credo][credo] and [Dialyzer][dialyxir] checks that can be
30+
run with `mix lint`.
31+
32+
[credo]: https://github.com/rrrene/credo
33+
[dialyxir]: https://github.com/jeremyjh/dialyxir
34+
[ot]: https://en.wikipedia.org/wiki/Operational_transformation
35+
[ot_text]: https://github.com/ottypes/text

‎lib/ot/text.ex‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,19 @@
11
defmodule OT.Text do
22
@moduledoc """
33
A [TP1][tp1] operational transformation implementation based heavily on
4-
[ot-text][ot_text] by Joseph Gentle, but modified to be invertable.
4+
[ot-text][ot_text], but modified to be invertable.
5+
6+
In this OT type, operations are represented as traversals of an entire string,
7+
with any final retain components implicit. This means that given the text
8+
"Foz Baz", the operation needed to change it to "Foo Bar Baz" would be
9+
represented thusly:
10+
11+
```elixir
12+
[2, %{d: "z"}, %{i: "o Bar"}]
13+
```
14+
15+
Notice that the final retain component, `4` (to skip over " Baz") is
16+
implicit and it not included.
517
618
[tp1]: https://en.wikipedia.org/wiki/Operational_transformation#Convergence_properties
719
[ot_text]: https://github.com/ottypes/text/blob/76870df362a1ecb615b15429f1cd6e6b99349542/lib/text.js

‎lib/ot/text/application.ex‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
defmodule OT.Text.Application do
22
@moduledoc """
3-
The application of a text operation to a text datum.
3+
The application of a text operation to a piece of text.
44
"""
55

66
alias OT.Text, as: Text
77
alias Text.Operation
88

99
@typedoc """
1010
The result of an `apply/2` function call, representing either success or error
11-
to apply an operation.
11+
in application of an operation
1212
"""
1313
@type apply_result :: {:ok, OT.Text.datum}
1414
| {:error, :delete_mismatch | :retain_too_long}
@@ -39,6 +39,9 @@ defmodule OT.Text.Application do
3939
@spec apply(Text.datum, Operation.t) :: apply_result
4040
def apply(text, op), do: do_apply(text, op)
4141

42+
@doc """
43+
Same as `apply/2`, but raises if the application fails.
44+
"""
4245
@spec apply!(Text.datum, Operation.t) :: Text.datum | no_return
4346
def apply!(text, op) do
4447
with {:ok, result} <- __MODULE__.apply(text, op) do

‎lib/ot/text/component.ex‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
defmodule OT.Text.Component do
22
@moduledoc """
3-
An individual unit of work to be performed on a text datum.
3+
An individual unit of work to be performed on a piece of text.
44
55
A component represents a retain or modification of the text:
66
@@ -14,19 +14,19 @@ defmodule OT.Text.Component do
1414

1515
@typedoc """
1616
A delete component, in which a string of zero or more characters are deleted
17-
from the text datum
17+
from the text
1818
"""
1919
@type delete :: %{d: Text.datum}
2020

2121
@typedoc """
2222
An insert component, in which a string of zero or more characters are inserted
23-
into the text datum
23+
into the text
2424
"""
2525
@type insert :: %{i: Text.datum}
2626

2727
@typedoc """
28-
A retain component, in which a number of characters in the text datum are
29-
skipped over
28+
A retain component, in which a number of characters in the text are skipped
29+
over
3030
"""
3131
@type retain :: non_neg_integer
3232

@@ -41,7 +41,7 @@ defmodule OT.Text.Component do
4141
@type comparison :: :eq | :gt | :lt
4242

4343
@typedoc """
44-
A single unit of "work" performed on a piece of text.
44+
A single unit of "work" performed on a piece of text
4545
"""
4646
@type t :: delete | insert | retain
4747

‎lib/ot/text/operation.ex‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
defmodule OT.Text.Operation do
22
@moduledoc """
3-
A list of components that iterates over a piece of text, possible making
4-
changes to it.
3+
A list of components that iterates over and/or modifies a piece of text
54
"""
65

76
alias OT.Text.Component

‎lib/ot/text/scanner.ex‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
defmodule OT.Text.Scanner do
22
@moduledoc """
33
Enumerates over a pair of operations, yielding a full or partial component
4-
from each.
4+
from each
55
"""
66

77
alias OT.Text.{Component, Operation}

‎mix.exs‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ defmodule Ot.Mixfile do
88
build_embedded: Mix.env == :prod,
99
start_permanent: Mix.env == :prod,
1010
deps: deps(),
11+
aliases: aliases(),
1112
dialyzer: [flags: ~w(-Werror_handling
1213
-Wrace_conditions
1314
-Wunderspecs
@@ -19,7 +20,7 @@ defmodule Ot.Mixfile do
1920
# Type "mix help compile.app" for more information
2021
def application do
2122
# Specify extra applications you'll use from Erlang/Elixir
22-
[extra_applications: [:logger]]
23+
[]
2324
end
2425

2526
# Dependencies can be Hex packages:
@@ -36,4 +37,8 @@ defmodule Ot.Mixfile do
3637
{:dialyxir, "~> 0.4", only: [:dev], runtime: false},
3738
{:credo, "~> 0.5", only: [:dev, :test]}]
3839
end
40+
41+
defp aliases do
42+
[lint: ["credo", "dialyzer --halt-exit-status"]]
43+
end
3944
end

0 commit comments

Comments
 (0)